# index

---
title: FAQs
side_nav_title: FAQs
side_nav_order: 1
description: Find answers to frequently asked questions about the Visa Product Design System.
meta_description: Find answers to frequently asked questions about the Visa Product Design System.
---

## About Nova

### What is Nova?

Nova is the latest version of the Visa Product Design System (VPDS). It embodies the team’s commitment to creating the next wave of Visa products and experiences, marked by enhanced cohesion and consistency.<br/><br/>
To learn more about Nova and VPDS, visit [What is VPDS?](https://design.visa.com/about-VPDS)

### What is the difference between Nova and Vault Key+?

Nova and Vault Key+ are major versions of VPDS. Vault Key+ is the third and final iteration of the Vault design system. All the code libraries provide low-level accessible [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/)<!-- aria-label="Web Content Accessibility Guidelines (WCAG) (opens in a new tab)" --> components to help build experiences that follow Visa’s brand and product guidelines. Nova components are built following [Visa Global Accessibility Requirements (VGAR)](https://developer.visa.com/pages/accessibility)<!-- aria-label="Visa Global Accessibility Requirements (VGAR) (opens in a new tab)" -->, meeting VGAR, WCAG 2.2, A, and AA standards.<br/><br/>
Nova is the current supported version of VPDS and will continue to receive support for the foreseeable future. Since many stable products use Vault Key+, it will continue to receive security and framework upgrades, as well as bug fixes for the foreseeable future. However, all future expansion efforts are now directed toward Nova.<br/><br/>
To learn more about VPDS versions, visit [Releases](https://design.visa.com/what's-new/releases).

### Why is Nova recommended over Vault Key+?

Nova is the latest version of VPDS and will continue to receive support for the foreseeable future. It includes new design tokens for easy theming, updated visuals, and new libraries for icons and mobile components. Nova components are available in [Angular](https://design.visa.com/developing/angular), [Flutter](https://design.visa.com/developing/flutter), [React](https://design.visa.com/developing/react), or [Styles (CSS)](https://design.visa.com/developing/styles-css).<br/><br/>
As with any version of our design system, always follow [VGAR Test Procedures](https://developer.visa.com/pages/accessibility/test-procedures)<!-- aria-label="VGAR Test Procedures (opens in a new tab)" --> to ensure experiences meet accessibility requirements.

### Does Nova have a stable release?

Yes. For more information, visit [Releases](https://design.visa.com/what's-new/releases).

### Is Nova compatible with Vault Key+?

Nova is the latest version of VPDS and is recommended for all new projects. Its [Angular](https://design.visa.com/developing/angular), [Flutter](https://design.visa.com/developing/flutter), [React](https://design.visa.com/developing/react), or [Styles (CSS)](https://design.visa.com/developing/styles-css) components can be used along with Vault Key+ components in stable Vault Key+ applications.<br/><br/>
Nova and Vault Key+ are separate libraries with different scopes and names, so Nova isn't backwards compatible with Vault Key+. This means you can't use Nova as a drop-in replacement for Vault Key+ because they are designed independently. However, both libraries can coexist in the same application using the same Styles (CSS), React, or Angular library versions.

### Can I use both Nova and Vault Key+ in the same project?

Yes, you can swap older, Vault Key+ components for Nova versions or add new features in Nova without upgrading the rest of your application.

### What is the process and support available for transitioning from Vault Key+ to Nova?

Nova and Vault Key+ can coexist to support a gradual transition to Nova. In addition, Nova is built with first-class theming capabilities to help make this transition smoother. Our team is available to provide help for migration plans as needed.<br/><br/>
To get help or join our office hours, visit [Support](https://design.visa.com/support).

### Are there any plans to sunset Vault Key+ ?

Currently, there are no plans to sunset Vault Key+. However, as technical specifications evolve and we notice reduced Vault Key+  usage from our analytics, the team may reconsider.

### When do I need to upgrade to Nova?

We recommend designing all new Visa products using Nova assets, but there's no mandated deadline for teams to upgrade to Nova.

### What if Nova doesn't have a component I need?

The VPDS team is continuously adding new assets to the system, including components. If there’s a component you need that’s not in our system, Visa employees can contact the VPDS team by visiting [Support](https://design.visa.com/support). 

### How do I report a bug or request a feature in Nova?

Reach out to the team for help by visiting [Support](https://design.visa.com/support).

## Design

### Can I customize or detach Nova components?

Yes, you can detach components. Many components, such as the Dynamic table, include subcomponents that are easier to manipulate once detached. However, remember that design software has limitations on customizing components, especially if you're creating a variant that isn’t in the design system yet. Ensure you communicate any customizations to your development team early and again during handoff.

## Development

### Can I use the latest Angular, React, or Flutter versions with Nova?

We regularly update to the latest library and framework versions to add new features, improvements, and security updates to our system while keeping our components stable and compliant.<br/><br/>
To learn more, visit the changelogs for [Angular](https://design.visa.com/developing/angular/changelog), [Flutter](https://design.visa.com/developing/flutter/changelog), [React](https://design.visa.com/developing/react/changelog), or [Styles (CSS)](https://design.visa.com/developing/styles-css/changelog).

### Can I use Nova with other design systems, like Bootstrap?

Nova's class names are unique, but other libraries might have CSS resets that can change the box model, root font size, or layout. We recommend moving away from any outdated libraries and embracing Nova to experience all its capabilities, along with modern Styles (CSS) features like Flexbox and Grid.

### Vault used to have a Grid component, but that's not available in Nova. What should I do?

The Grid component within Vault was a layout utility that was created to support old browsers. VPDS encourages teams to embrace modern CSS features like Flexbox and CSS Grid within Nova, which offer more powerful and flexible layout options.<br/><br/>
For more information, reference [Grid resources (internal only)](https://bookmarks.visa.com/vpds-angular-foundations-grid)<!-- aria-label="Grid resources (internal only, opens in a new tab)" -->.

## Accessibility

### Does VPDS provide accessibility guidance?

Yes, VPDS provides accessibility guidance for components and patterns to help designers and developers create inclusive digital products. We also provide Visa’s Global accessibility requirements, which ensure that Visa’s digital products meet global accessibility standards. These requirements help in planning, design, and development to prevent costly rework. <br/><br/>
To learn more, visit [Global accessibility requirements](https://design.visa.com/global-accessibility-requirements).

### Have VPDS components been accessibility reviewed and tested?

Yes. Nova components are built following VGAR, meeting VGAR, WCAG 2.2, A, and AA standards. 

### Are VPDS components and assets routinely regression tested?

Yes, VPDS components are regression tested annually.

## Content

### Does VPDS provide guidance for writing content?

Yes. To learn more about crafting thoughtful and concise content, visit [Content](https://design.visa.com/content).

### Have VPDS assets been content reviewed?

The Content Design team has partnered with Accessibility to review all available VPDS components for descriptive headings, labels, and more. Additionally, all assets have been reviewed ensuring they follow content guidance for [Placeholder text](https://design.visa.com/content/placeholder-text). This means when you use a VPDS component, medium fidelity placeholder content has been added to help your team further edit and customize components.

## Data visualization

### What are Visa Chart Components?

Visa Chart Components (VCC) are a library of accessible web chart components with robust accessibility configurations to enhance your workflow and ensure your product meets the latest accessibility standards. The VCC library is maintained to provide charts that work alongside VPDS components. VCC can be used with React, Angular, and Vanilla JavaScript.<br/><br/>
To learn more, visit [Visa Chart Components](https://design.visa.com/data-visualization).

### What if I need a chart that's not in Visa Chart Components?

Visa employees can contact the Data Experience team to discuss needs for any charts that aren’t available in Visa Chart Components (VCC).<br/><br/>
To get connected with the Data Experience team, visit [Support](https://design.visa.com/support).

---

# index

---
title: Inclusive design
description: Gain insight into the use of inclusive design to ensure Visa products include everyone, everywhere.
meta_description: Learn how to implement inclusive design to ensure Visa products include everyone, everywhere.
thumbnail: assets/about-vpds/inclusive-design/inclusive-design-graphic.svg
header_image: assets/about-vpds/inclusive-design/inclusive-design-overview.svg
related:
  content:
    - index
---

Inclusive Design considers the full range of human uniqueness and the diversity of perspectives, abilities, and backgrounds throughout the product design and development process. The intent is to fulfill as many needs as possible and drive innovation that unlocks equitable, accessible, and ethical experiences. This guidance provides an overview of key concepts and their impacts, such as how Design@Visa infuses Inclusive Design throughout its practices and embodies an equity-driven approach.

## Best practices

### Embody an equity-based approach

Strive for an equity-based approach. When designing, we start by addressing the needs of underrepresented groups, ensuring fair treatment and opportunity, and then design outward. This approach helps us create digital experiences that are truly inclusive and beneficial to all users.
<br/>
This is the counterpart to an equality-based approach, in which resources are allocated equally regardless of barriers that may prevent some groups from accessing or utilizing them. In an equity-based approach, fair treatment and opportunity are afforded while striving to deconstruct barriers that prevent the all groups from participating equally. 

### Embrace the complexity of human uniqueness

Human identities are complex intersections of various factors such as class, gender, ethnicity, and more. These elements interplay and can’t be singled out to determine how inequity impacts an individual. During your product design process, respect this complexity to build digital experiences that enhance access and reduce barriers for all users, especially those from underrepresented groups.

### Avoid centering on dominant culture

Consciously avoid designing from the perspective of a dominant culture, which often becomes the default lens for design decisions. Recognizing dominant defaults allows us to disrupt these norms, creating more inclusive designs.
<br/>
One way to accomplish this is by using the term “misrepresented” instead of “marginalized,” “underserved,” “unserved,” “vulnerable,” or similar terms. Misrepresented identities are those that have been defined by the dominant culture and denied the ability to define themselves on their own terms. They are falsely or narrowly represented.  In terms of financial terminology, avoid phrases like "underbanked" or "unbanked," as they don’t fully encompass financial inclusion. Instead, use "underinvested".

### Strive for greater financial inclusion

As a global leader in digital payments, Visa is committed to fostering inclusion, particularly financial inclusion, as a part of our corporate responsibility. Our mission is to uplift all individuals, everywhere, by providing the best payment solutions. Strive to dismantle barriers to financial access, such as expanding account accessibility to include more participants in the global economy.

## Inclusive design process
The design process is the way in which product teams approach meeting a user need and is imperative to bringing a product to market. The core group of cross-functional team members, or Triad, is responsible for product delivery and are responsible for proactively addressing inclusion at every step of the process. The Triad includes a product lead, a design lead, and a technology lead (engineering). All three are involved in all the conversations of end-to-end product delivery. 

### The design process at Visa 
Our design process is an iterative approach in which: 
- Design is an end-to end partner to product, technology, and beyond
- Designers work iteratively to discover, define, develop, and deliver great experiences and outcomes
- Design teams are structured across three pillars: Opportunity, Experience, and Solution

#### Human-centered design and inclusive design

Inclusive Design is a part of human-centered design, where both put real humans and the problems they face at the center of the design and development process. At its core, human-centered design is based on a philosophy made to ensure products and services are tailored to the needs of as many users within an audience as possible.<br/><br/>
Inclusive design is more focused and considers the full range of human diversity, including physical and mental abilities, language, race, gender, age, and other forms of human differences. It aims to drive innovation that unlocks equitable, accessible, and ethical experiences for all backgrounds and abilities. When practicing human-centered design, inclusive design should be considered a part of your process.

#### Universal design and accessible design

Universal and accessible design are often confused for one another. While the two concepts are closely related to inclusive design, accessibility is focused on ensuring that people of all abilities can use digital products and tools equally, where universal design aims to create one experience that can be accessed, understood, and used to the greatest extent possible by all users with a wide range of abilities, disabilities, and other characteristics.<br/><br/>
Universal design differs from human-centered design as universal design is more conceptual and philosophical, while user-centered design process-focused. When using human-centered design processes, keep inclusive, universal, and accessible design philosophies and methodologies in mind to help reduce barriers between humans and technology.

## Inclusive research
Design research is heavily involved in the Discover and Define phases of the design process. These phases focus on deep discovery of a user need (getting the right need) and definition of the need (getting the need right), while surfacing recommendations for when a solution gets designed. Research is user-driven, as it is directed at generating new ideas or evaluating what’s been built to provide the best experience possible for users. Design research should be performed by design researchers, and in the absence of design researchers, designers, developers, and product managers should partner to ensure inclusion is incorporated in the design process. Teams should consult with the design research organization to ensure they are measuring their product team inclusion (using the Inclusion score), and incorporating inclusion into their process in the recommended manner.<br/>

### Examples of how design research can boost inclusion:

- Validate that the need actually exists with users (don’t design for something they don’t need)
- Include the right data by ensuring there’s a proper sample size to provide useful feedback and including secondary and tertiary personas in addition to primary personas..
- Enlist co-design, a participatory approach in which the community of users is treated as an equal collaborator
- Ensure diversity of collaborators, and involve them early in the design process

## Impact
Companies are expected to be transparent around their business approach now more than ever. ​Consumers have become more conscious as they desire to align themselves with brands, companies, and products that share their social, political, and moral values.

### Financial inclusion
As a global leader in digital commerce and finance, Visa processes billions of transactions daily and drives economies worldwide with its vast payment network. This positions us uniquely to foster global financial inclusion. It's our responsibility to ensure our services are designed for all individuals and businesses, regardless of their demographic or business attributes. We also have the capacity to create opportunities for those previously unable to partake in local and global economies.<br/><br/>
To achieve this, we apply inclusive design practices in our focused areas. Throughout the design and development lifecycle, the cost of change can escalate considerably. However, this can be mitigated by understanding the real needs of users and businesses and translating these needs into appropriate specifications from the beginning of the design process.

### Opportunities within payment
Within the payments space there are many emerging B2C and B2B business cases to build more inclusive products. Below are a few examples of how Visa is working to create inclusive experiences.<br/><br/>

<FeatureWithIcon icon={VisaIssuerHigh}>
  <Typography variant="subtitle-1">Enabling digitally inclusive government-to-citizen payments​</Typography>
  <Typography variant="body-2">Designing with government beneficiaries and financial institutions to increase cards used as a payment tool instead of a cash-access tool in government disbursement programs.</Typography>
</FeatureWithIcon>

<FeatureWithIcon icon={VisaMoneySendHigh}>
  <Typography variant="subtitle-1">Increasing affordability with installments</Typography>
  <Typography variant="body-2">Designing with consumers to help manage cash flow and budget based on their current financial position.</Typography>
</FeatureWithIcon>

<FeatureWithIcon icon={VisaDeviceMobileHigh}>
  <Typography variant="subtitle-1">Ensuring global mobility with Tap to Phone</Typography>
  <Typography variant="body-2">Designing with consumers and small- and mid-sized businesses may to help increase the types of phones that work with Tap to Phone (TTP).</Typography>
</FeatureWithIcon>

<FeatureWithIcon icon={VisaCardGenericHigh}>
  <Typography variant="subtitle-1">Allowing chosen name on credit cards</Typography>
  <Typography variant="body-2">Designing with LGBTQIA+ consumers and financial institutions to reduce false positives on credit applications, or help issuers avoid deadnaming LGBTQIA+ community members.</Typography>
</FeatureWithIcon>

#### ESG reports

- Explore Visa’s current and past [Environmental, Social and Governance Reports](https://usa.visa.com/about-visa/esg/resources.html)<!-- aria-label="Environmental, Social and Governance Reports (opens in a new tab)" --> to learn how we’re delivering our purpose to uplift everyone, everywhere by being the best way to pay and be paid.

#### Case studies

- Learn how Visa is [collaborating with Fintech partners](https://usa.visa.com/audiences/fintech.html)<!-- aria-label="collaborating with Fintech partners (opens in a new tab)" --> to help pioneer new modes of commerce and new ways to pay.

#### White papers

- Explore the [Visa Economic Empowerment Institute’s white papers](https://usa.visa.com/sites/visa-economic-empowerment-institute/digital-financial-inclusion.html)<!-- aria-label="Visa Economic Empowerment Institute’s white papers (opens in a new tab)" -->  on fostering digital inclusion.  

## Resources (internal only)
- [VGAR SharePoint](https://bookmarks.visa.com/va11y-sharepoint)<!-- aria-label="VGAR SharePoint (opens in a new tab)" --> 
- [Inclusion & Diversity Hub](https://bookmarks.visa.com/vpds-inclusion-diversity-hub)<!-- aria-label="Inclusion & Diversity Hub (opens in a new tab)" -->


---

# index

---
title: What is VPDS?
side_nav_title: What is VPDS?
description: Learn more about the Visa Product Design System.
---

The Visa Product Design System (VPDS) is an all-encompassing toolkit designed to revolutionize the product design and development process. Recognized across Visa’s product ecosystem, VPDS:
- Enhances collaboration among teams.
- Ensures brand consistency throughout products.
- Accelerates time to market across various platforms.
<br/>
This robust system unifies design and development, offering a cohesive approach to creating digital products. Utilizing VPDS helps your product:
- Seamlessly integrate with other Visa offerings.
- Facilitate the creation of intuitive user experiences.
- Resonate with Visa's brand values.

## What are the benefits of VPDS?
VPDS simplifies the product development lifecycle, empowering your team to innovate and deliver high-quality products that go to market faster. The key benefits include:
- **Efficiency:** Accelerate design and development with pre-built components, reducing repetitive tasks and rework.
- **Accessibility:** Create accessible experiences using libraries pre-tested for global accessibility standards.
- **Consistency:** Use standardized guidelines, components, and patterns to uphold brand trust and user satisfaction.
- **Collaboration:** Follow best practices and principles embedded in the system to enable effective teamwork.
- **Scalability:** Keep products forefront with regular updates based on user feedback and industry standards.
- **Innovation:** Drive innovation by allowing your team to focus on creative solutions while VPDS covers the basics.
<br/>

<Testimonial
    quote="As a designer, being able to drag-and-drop the components [in Figma] allowed us to focus on the bigger picture, rather than messing with all the details."
    author="Design intern, Risk and Identity Product Design Intern, Visa"
/>

## What is a design system?
Design systems provide a centralized library of assets and guidelines to ensure consistency and efficiency. This includes extensive libraries of pre-built components, design patterns, and comprehensive content guidelines, all tailored to meet the highest standards of accessibility, usability, and aesthetic excellence. VPDS supports [design kits](https://design.visa.com/designing/design-kits) in Figma and code libraries for [Angular](https://design.visa.com/developing/angular), [React](https://design.visa.com/developing/react), [Styles (CSS)](https://design.visa.com/developing/styles-css), and [Flutter](https://design.visa.com/developing/flutter). These resources are continuously updated based on user feedback and the latest technological advancements. By leveraging these assets, teams can streamline their workflows, foster innovation, and create cohesive user experiences across all Visa products.

<img src="https://design.visa.com/assets/about-vpds/vpds-ecosystem.svg" alt="Image showing the different parts of the VPDS ecosystem including components, base elements, patterns, content, data visualization, design kits, and code libraries"/>

## What's the history of VPDS?
VPDS has undergone several releases since Hamlet launched in 2018. Each release has brought improvements in scale, usability, and accessibility based on community feedback. Support for Hamlet ended in 2022, followed by its successors Vault and Vault Key. The third and final version of the Vault system, Vault Key+, continues to receive support and fixes for the foreseeable future. <br/><br/>

The latest version of the design system is called Nova. Inspired by the astronomical phenomenon, Nova symbolizes a burst of energy and innovation. This version embodies the VPDS team’s commitment to creating the next wave of Visa products and experiences, marked by enhanced cohesion and consistency. Just as a Nova signifies a powerful transformation in the cosmos, this release represents a significant leap forward in Visa’s design system. <br/><br/>

Product teams are encouraged to begin migrating to this version as it will continue to receive new additions and support moving forward. For more information on current and past versions, visit [Releases](https://design.visa.com/what's-new/releases). 

## Who manages VPDS?
The Visa Product Design System is managed by a collaborative team of designers, developers, content designers, accessibility partners, researchers, and ops. Collectively, the team ensures the system remains current and effective by continuously updating resources based on cross-discipline reviews, user feedback, and industry best practices. To connect with the VPDS team or learn more about office hours or quarterly updates, visit [Support](https://design.visa.com/support). 

<img src="https://design.visa.com/assets/about-vpds/vpds-partners.svg" alt="Image showing gears labeled Design ops, Content design, Accessibility, Design, Development, and research"/>

## Ready to get started?
Transform your product design and development process by choosing one of the paths below. 
<br/>

<div className="v-flex v-gap-12 v-flex-wrap">
<a href={`https://design.visa.com/designing`} class="v-button v-button-secondary">Start designing</a>
<a href={`https://design.visa.com/developing`} class="v-button v-button-secondary">Start developing</a>
</div>

---

# Usage

---
title: Color
description: Learn how to use Visa brand colors to create and maintain consistent and engaging experiences. 
tab_title: Usage
tab_order: 1
keywords: ["color", "brand colors", "color contrast", "color palette", "contrast"]
tags:
  - colors
  - brand
  - accessibility
---

Colors used within the Visa Product Design System were adapted from Visa brand colors for digital products and experiences. These colors were designed to provide flexibility to designers and developers, including themes for Visa-branded products and generic colors which serve as a starting point for representing clients and fictitious brands. 
<br />
Reference Visa brand guidance for more information on color use outside product design.

## Best practices

## Active colors
Active colors are the primary color used to indicate interactivity. Active subtle is used for interactive pieces that need less emphasis but sufficient contrast. 

<img src="https://design.visa.com/assets/base-elements/color/color-active.svg" alt="Visa active color palette." style={{marginBlockEnd: '0'}} />

## Surface colors
Surface colors are used for the largest background areas of an application. They are also used as backgrounds on subtler interactive elements in combination with active colors, such as in the secondary button. 

<img src="https://design.visa.com/assets/base-elements/color/color-surface.svg" alt="Visa surface color palette." style={{marginBlockEnd: '0'}}/>

## Text colors
Text colors are used to ensure readability and accessibility. They are applied to various text elements such as headings, body text, and labels, and are chosen to provide sufficient contrast against background colors.

<img src="https://design.visa.com/assets/base-elements/color/color-text.svg" alt="Visa text color palette." style={{marginBlockEnd: '0'}}/>

## Decorative colors
Decorative colors are only applied to elements that don’t have color contrast requirements, such as disabled components or container borders. They add visual interest and enhance the aesthetic appeal without impacting functionality or readability.

<img src="https://design.visa.com/assets/base-elements/color/color-decorative.svg" alt="Visa decorative color palette." style={{marginBlockEnd: '0'}}/>

## Messaging colors
Messaging colors are used for components like [Section messages](https://design.visa.com/components/section-message/usage), [Flags](https://design.visa.com/components/flag/usage), [Banners](https://design.visa.com/components/banner/usage), and [Dialogs](https://design.visa.com/components/dialog/usage), to communicate the urgency of a message or alert. These colors are used sparingly to ensure they don’t overwhelm the primary content.

<img src="https://design.visa.com/assets/base-elements/color/color-messaging.svg" alt="Visa messaging color palette." style={{marginBlockEnd: '0'}}/>

## Color for Visa-branded products
All Visa-branded products should use the Visa theme palette along with the alternate palette to achieve a consistent experience that accurately represents the Visa brand.

## Theme background colors
The Visa theme contains two background colors that allow you to change between a default and alternate color treatments. These were designed for navigation headers and bold splash screens. Changing the theme background color will automatically adjust the design tokens to ensure accessibility contrast ratios are met. 

<img src="https://design.visa.com/assets/base-elements/color/color-theme-bg.svg" alt="A side-by-side view of two vertical nav components, one using the Visa theme palette and the other using the alternate palette" style={{marginBlockEnd: '0'}}/>
- Use the alternate palette sparingly and intentionally. Too much color variation can disorient or overwhelm users.

## Visa light and Visa dark modes
The Visa light theme serves as the default mode for most use cases, providing a clean and consistent user experience. The Visa dark theme offers an alternative mode for Visa-branded applications, reducing eye strain in low-light environments with its darker colors. Learn more about themes and modes in [Design tokens](https://design.visa.com/base-elements/design-tokens/overview).

<img src="https://design.visa.com/assets/base-elements/color/color-light-dark.svg" alt="A side-by-side view of a web layout, one using the Visa light theme palette and the other using the dark palette." style={{marginBlockEnd: '0'}}/>

## Color for data visualization
Color can be used as a tool to communicate meaning in data visualizations. To learn how to select the most effective type of color palette for your data visualization, reference the Data Experience team’s design guide for [Color (internal only)](https://bookmarks.visa.com/vpds-vcc-color-guidelines).  


---

# accessibility

---
title: Color
description: Learn how to use Visa brand colors to create and maintain consistent and engaging experiences.
meta_description: Learn how to use Visa brand colors to create and maintain consistent and accessible experiences.
tab_title: Accessibility
tab_order: 2
tags:
  - colors
  - brand
  - accessibility
---

## Using color for meaning
While color is an important, it should never be used alone to convey meaning. Always pair color with another communication method, such as text or icons, to ensure everyone can understand and interact with Visa products. 

## Color contrast for accessibility
Color is measured by the visual contrast between an element and the surface it appears on. Ensuring colors pass contrast requirements means combining them intentionally. When creating your own theme or custom designs, follow the patterns in the Visa theme palette to make sure your product is accessible. 
<br/>
If you make changes to Visa theme colors, there are many free browser extensions and other tools which test contrast on a page.
<br/>
**Note:** Disabled controls are not subject to color contrast ratios.
- Ensure text uses foreground colors with a contrast ratio above 4:5:1.
- Ensure user interface elements, graphics, and text that are 14 point bold or larger, use foreground colors with a ratio above 3:1.

### High contrast

Users can select settings in their operating system to increase color contrast because of visual impairment, to reduce eye strain, to reduce distractions, or personal preference. VPDS components and themes handle high contrast modes out of the box. However, please note the following, especially if you use custom themes, icons, or logos. For more, reference [Horizontal navigation](https://design.visa.com/components/horizontal-navigation/accessibility) or [Vertical navigation](https://design.visa.com/components/vertical-navigation/accessibility). 
<br/>
CSS media queries are used to target OS high contrast settings. There’s also a media query to determine whether a page has a light or dark background. Automated testing doesn’t test page appearance or meaning in high contrast modes. For this reason, manual testing is especially important for Windows high contrast mode.

### Windows high contrast mode

Windows high contrast mode completely removes background colors and background images with limited exceptions. It also sets text colors, form control colors, borders and outlines according to the theme chosen by the user.
- Replace box shadows with borders or outlines as the shadows will be automatically removed. 
- Ensure outlines don’t conflict with focus styles.
- Consider using a border or outline in HC mode if background colors are used to demarcate a section of the page.
- `img` elements are not changed.

## Data visualization
There are additional color requirements for visualizing data. Reference [Data visualization](https://design.visa.com/data-visualization).



---

# index

---
title: Color
description: Learn how to use Visa brand colors to create and maintain consistent and engaging experiences. 
meta_description: Get code for Visa brand colors to create and maintain consistent and engaging experiences.
thumbnail: assets/base-elements/color/color-graphic.svg
tab_title: Code
tab_order: 0
tags:
  - colors
  - brand
  - accessibility
---

<ColorCodePage componentName="color" />


---

# index

---
title: About design tokens
side_nav_title: Overview
side_nav_additional_screenreader_title: for Design tokens
description: Explore guidance for using design tokens or variables to customize themes and experiences.
meta_description: Use design tokens and themes to customize your product experiences, ensuring consistency, scalability, and accessibility.
thumbnail: assets/base-elements/design-tokens/design-tokens-graphic.svg
related: 
  baseElements:
    - color
    - typography
---

## What are design tokens?
Design tokens are name-value pairs that define small, repeatable design decisions. Tokens can represent colors, typography, spacing, or even icons tailored to specific needs. Designers can use Visa Product Design System (VPDS) design tokens in Figma to easily adjust visual properties, while developers can modify a set of global variables to achieve the same effect in code. 

## What is theming?
Theming is the practice of using a collection of token values to achieve a specific look or style. A theme is essentially a predefined set of tokens designed to work together harmoniously. Examples of themes include Visa light and dark. Theming can also extend beyond colors to include elevation, spacing, and shape and size. 

### Theming terms

Definitions of theme, design token, and value

- Term: A collection of visual attributes assigned to the tokens in order to create a specific aesthetic.

- Term: A role-based identifier that assigns a value to a theme. Design tokens are universal and never change across themes. These are sometimes referred to as variables although not all variables are design tokens.

- Term: The actual style (such as a hex code) assigned to a token.

## Themes in our system

### Visa

The Visa theme supports light and dark modes. This theme automatically defaults to your system's preferences unless you override this behavior. Learn more about [switching between light and dark modes](https://design.visa.com/base-elements/design-tokens/tokens-for-developers#switching-between-light-and-dark-modes).
<img src="https://design.visa.com/assets/base-elements/design-tokens/visaTheme.svg" alt="A generic form in Visa light theme. The background is light gray and white, text is black, UI and icons are dark blue. One button has a red notifications icon."/>

### Default

The Default theme uses the VPDS color theming system for non-Visa branded products. It supports light and dark modes and automatically defaults to your system's preferences unless you override this behavior. Learn more about [switching between light and dark modes](https://design.visa.com/base-elements/design-tokens/tokens-for-developers#switching-between-light-and-dark-modes).
<img src="https://design.visa.com/assets/base-elements/design-tokens/defaultTheme.svg" alt="A generic form in Visa dark theme. The background is dark gray and black, text is white, UI and icons are gold. One button has a white notifications icon."/>

## Theme elements
VPDS supports theming at various levels, from broad adjustments to component-specific changes. Both CSS and Figma can be used to override system values for color, typography, icons, elevation, shape and size, and spacing.

### Color
Colors can be adjusted to represent Visa, our clients, or fictitious companies. Each theme is assigned universal color variables based on common roles and usage, ensuring uniform color application across themes while maintaining full styling flexibility. Always consider contrast requirements to ensure designs are accessible to all users. <br/><br/> For more information, visit [Color.](https://design.visa.com/base-elements/color)

### Typography
Visa Dialect UI is the standard font for Visa-branded digital interfaces. For non-Visa branded experiences, you can adjust the font choice as needed, but avoid using Visa Dialect or Visa Dialect UI. Mobile applications may benefit from using native fonts based on the platform to take advantage of built-in features. For browser-based applications, we recommend Open Sans. Maintain the size ratios shown in the type ramp to ensure consistent text hierarchy across experiences. <br/><br/>
For more information, including our type ramp, visit [Typography.](https://design.visa.com/base-elements/typography)

### Icons
VPDS currently supports two sets of icons: Visa-branded and generic, to represent ideas, actions, and entities. Products using the Visa theme should use the Visa icon set, while all non-Visa themes should use the generic set.<br/><br/> To learn more about the icons available for use, visit [Icons and illustrations.](https://design.visa.com/components/icons-illustrations)

### Elevation
Elevation tokens define the perceived surface level and shadow, creating depth and hierarchy in your designs. These help simulate realistic lighting and layering effects, ensuring a cohesive and polished visual experience. <br/><br/> For more information, including how to layer elements in CSS, React, and Angular, visit [Elevation.](https://design.visa.com/base-elements/elevation)

### Size and shape
Size and shape define the corner rounding and dimensions of components within the system. Use the Figma assets panel to apply preset rounding options, such as Square, Less rounded, More rounded, or Full rounded. Similarly, the size of individual design elements or entire layouts can be scaled up or down to fit your use case. <br/><br/> For more information, visit [Size and shape.](https://design.visa.com/base-elements/size-and-shape)

### Spacing
Spacing refers to the blank space inside and around elements to achieve various levels of visual density. Use the Figma assets panel to apply preset spacing options, including Dense, Default, or Spacious layouts.  <br/><br/> For more information, visit [Spacing.](https://design.visa.com/base-elements/spacing)

## Customizing a theme
Designers and developers can customize their components and styles to deviate from the default Visa light theme. Within Figma, designers can modify one, some, or all of the default token values to create a new theme. Developers can configure these new values in the appropriate files, either replacing the default values or adding new custom tokens. <br/><br/>

<div className="v-flex v-gap-12 v-flex-wrap">
  <a href={`https://design.visa.com/base-elements/design-tokens/tokens-for-designers`} class="v-button v-button-secondary v-mr-8">Design tokens for designers</a>
  <a href={`https://design.visa.com/base-elements/design-tokens/tokens-for-developers`} class="v-button v-button-secondary">Design tokens for developers</a>
</div>


---

# index

---
title: Design tokens for designers
description: Learn how to leverage design tokens to customize components effortlessly while maintaining a cohesive visual identity and experience.
side_nav_title: Tokens for designers
show_on_overview: false
---

## Before you begin
Make sure you understand the basics by visiting [Design tokens and theming](https://design.visa.com/base-elements/design-tokens/overview). 

### Common use for design tokens and theming

- **White labeling for non-Visa products:** Easily adapt your designs for external brands.
- **Mockups using fictitious brands:** Create realistic prototypes for presentations and pitches.

### Common ways to theme in Figma

- **Batch adjust components with presets:** Use variable modes to change multiple components simultaneously.
- **Create custom themes:** Modify one, some, or all of the default token values (variables) to create a new theme.

## Using variable mode presets
Design tokens are represented by variables within Figma. These variables can be changed to alternate preset values through the Figma user interface. Using variable modes helps to ensure that customizations are within the design system’s rules and capabilities. For example, the color themes have been tested to ensure proper contrast when applied to VPDS components.

### Step 1: Select a page, frame, or component

Add or select a component within your workspace to activate the properties panel on the right. Select the **Apply variable mode** button, represented by an icon of two hexagons with a dot in the middle, to explore the presets.

### Step 2: Start customizing

Once you’ve explored the presets provided by VPDS, use the variable modes to swap the theme background, typography, shape, and more. You can also select multiple components or the entire frame to apply consistent styles. 

<img src="https://design.visa.com/assets/base-elements/design-tokens/theming-design-2.svg" alt="Two accordion components with different theme color, padding, and shape variables applied."/>
The table below includes the names of the base elements, along with their corresponding variable mode in Figma, and preset values. These will help you navigate the system and customize your designs effectively.

Base elements mode, presets and tokens

- Base element: Color theme
- Variable mode: Visa light, Visa dark, Gray blue light, Gray blue dark, Purple light, Purple dark, Green light, Green dark, Black and white light, Black and white dark
- Preset values: [Color](https://design.visa.com/base-elements/color)

- Base element: Platform
- Variable mode: Web, mobile
- Preset values: N/A

- Base element: N/A
- Variable mode: N/A
- Preset values: [Elevation](https://design.visa.com/base-elements/elevation)

- Base element: N/A
- Variable mode: Visa, Generic (modified through properties)
- Preset values: N/A

- Base element: N/A
- Variable mode: Use Figma scale tool
- Preset values: [Size and shape](https://design.visa.com/base-elements/size-and-shape)

- Base element: Shape
- Variable mode: Rounded (default), Less rounded, Full rounded, square
- Preset values: [Size and shape](https://design.visa.com/base-elements/size-and-shape)

- Base element: Padding
- Variable mode: Default, Spacious, Dense
- Preset values: [Spacing](https://design.visa.com/base-elements/spacing)

- Base element: Typography
- Variable mode: Visa Dialect UI, Open Sans, Noto Sans, SF Pro, Roboto
- Preset values: [Typography](https://design.visa.com/base-elements/typography)

## Create custom themes
Customizing beyond the provided properties can create additional development work. For maximum efficiency, continue the application of system rules throughout your customizations whenever possible. To make implementation of custom themes easier for your team:
- Edit the values of the existing design tokens (linked in the table above).
- Define values for a custom color theme by understanding how colors are applied to components to ensure proper contrast. Visit [Color accessibility](https://design.visa.com/base-elements/color/accessibility) to learn more.
- Create custom components using existing design system components as building blocks whenever possible. Follow system rules for communicating [States](https://design.visa.com/base-elements/states).


---

# index

---
title: Design tokens for developers
description: Use design tokens to customize your applications with consistent, scalable theming.
meta_description: Learn how to leverage design tokens to customize your applications with consistent, scalable theming.
side_nav_title: Tokens for developers
show_on_overview: false
---

## Before you begin
Make sure you understand the basics by visiting [Design tokens and theming](https://design.visa.com/base-elements/design-tokens/overview) or reference the following overview. 

## Understanding base elements
The base elements of our system represent visual aspects that can be themed at various levels, from broad adjustments to component-specific changes. These elements include accessibility styles, color, elevation, icons, shape and size, spacing, and typography. 

&nbsp;

This page provides an introduction to app-level and component-level theming for web and mobile. To find tables containing the variables of each element and their default values, reference the Code tabs of each of the following:

- [Accessibility styles](https://design.visa.com/developing/styles-css/accessibility-styles)
- [Color](https://design.visa.com/base-elements/color)
- [Elevation](https://design.visa.com/base-elements/elevation)
- [Icons and illustrations](https://design.visa.com/components/icons-illustrations/code)
- [Size and shape](https://design.visa.com/base-elements/size-and-shape)
- [Spacing](https://design.visa.com/base-elements/spacing)
- [Typography](https://design.visa.com/base-elements/typography)

## Theming for mobile (Flutter)
There are two types of theming that can be performed using our library: App-level theming and widget-level theming.

### App-level theming
The following provides an example of how to apply light and dark mode as an app-level theme.

#### Step 1: Add light and dark theme

Under your MaterialApp(), add both light and dark theme:

<Utility vMarginTop={16}>
    <CodeSnippet isStandalone={true} exampleName='nova-flutter-theming' client:only="react" isTabs={false} code={addLightDarkTheme} language="dart">
    </CodeSnippet>
</Utility>

#### Step 2: Add the provider package

Next, add provider package in your pubspec.yaml. In your main .dart file, create a ThemeProvider, provide your themeData, and wrap your app with it:

<Utility vMarginTop={16}>
    <CodeSnippet isStandalone={true} exampleName='nova-flutter-package' client:only="react" isTabs={false} code={addProvidedPackage} language="dart">
    </CodeSnippet>
</Utility>

#### Step 3: Switch the theme

Then, anywhere in your code, call <VariableCodeFormatter codeText={"themeProvider.switchLightTheme()"}/> and <VariableCodeFormatter codeText={"themeProvider.switchDarkTheme()"} /> to switch the theme. In the code example above, you'll notice that the font is now customizable. But don't forget to add your fonts in your pubspec.yaml.

<Utility vMarginTop={16}>
    <CodeSnippet isStandalone={true}  exampleName='nova-flutter-switch-themes' client:only="react" isTabs={false} code={switchTheme} language="dart">
    </CodeSnippet>
</Utility>

### Widget-level theming
Theming can also be performed at the widget level. This example shows how to change the theme of a button to VButtonSecondary. 

<Utility vMarginTop={16}>
    <CodeSnippet isStandalone={true} exampleName='nova-web-widget-theming'  client:only="react" isTabs={false} code={widgetLevelTheming} language="dart">
    </CodeSnippet>
</Utility>

## Theming for web
Theming for web can be performed at the app-level or component-level using CSS variable overrides.

### App-level theming
The following theming configuration allows you to modify a small set of variables for maximum impact across components.

<Utility vMarginTop={16}>
    <CodeSnippet isStandalone={true} exampleName='nova-flutter-app-theming'  client:only="react" isTabs={false} code={appLevelTheming} language="dart">
    </CodeSnippet>
</Utility>
<br />
- <VariableCodeFormatter codeText={"--theme-responsive-factor"}/> controls how components and sizes adapt on smaller screens, below the mobile breakpoint. 
- <VariableCodeFormatter codeText={"--theme-scale-factor"}/> controls how much space appears between elements, making the UI feel more compact with smaller values or more relaxed with larger values.

### Switching between light and dark modes
Learn how to switch between light and dark modes using our Nova web libraries.

#### Step 1: Import your chosen theme
The Visa and Default themes support light and dark modes. Reference the Get Started guides for [Angular](https://design.visa.com/developing/angular), [React](https://design.visa.com/developing/react), or [Styles(CSS)](https://design.visa.com/developing/styles-css) for instructions on how to import themes into your application.

#### Step 2: Set the theme attribute
Apply a data-theme attribute to your <VariableCodeFormatter codeText={"html"}/>tag. The possible values are light or dark.

<br/>
**Note:** The Visa and Default themes automatically default to your system's light or dark mode preference. To override this behavior and use your desired mode, set the data-theme attribute to light or dark.
<Utility vMarginTop={16}>
    <CodeSnippet isStandalone={true} exampleName='nova-web-data-theme' client:only="react" isTabs={false} code={dataTheme} language="html">
    </CodeSnippet>
</Utility>

#### Step 3: Switch the mode
To switch between light and dark modes, change the value of the data-theme attribute. This example uses plain Javascript, but you can also use React or Angular to manage the theme state and switching logic.

<Utility vMarginTop={16}>
    <CodeSnippet isStandalone={true} exampleName='nova-web-switch-theme' client:only="react" isTabs={false} code={switchThemeWeb} language="javascript">
    </CodeSnippet>
</Utility>

#### Best practices for switching modes
- For accessbility purposes, consider defaulting to the user's system preferences for light or dark mode. This can be done by checking the prefers-color-scheme media query.
- Use local storage or cookies to save the user's preferences if you want the theme to persist across page reloads.

### Color
The simplest way to customize your application colors is by adjusting the palette.

<Utility vMarginTop={16}>
    <CodeSnippet isStandalone={true} exampleName='nova-flutter-color'  client:only="react" isTabs={false} code={color} language="dart">
    </CodeSnippet>
</Utility>

### Typography
To override the typography value, you can use CSS variables or utilities. 

<Utility vMarginTop={16}>
    <CodeSnippetTabs  exampleName='nova-flutter-typography' client:only="react" tabsList= {['CSS variables', 'Utilities']} code={typography} language="dart">
    </CodeSnippetTabs>
</Utility>

### Padding
To override the padding value, you can use CSS variables or utilities.
<Utility vMarginTop={16}>
    <CodeSnippetTabs exampleName='nova-flutter-padding'  client:only="react" tabsList= {['CSS variables', 'Utilities']} code={padding} language="dart">
    </CodeSnippetTabs>
</Utility>

### Shape
The simplest way to customize the shape is by adjusting the corners.

<Utility vMarginTop={16}>
    <CodeSnippet isStandalone={true} exampleName='nova-flutter-shape'  client:only="react" isTabs={false} code={shape} language="dart">
    </CodeSnippet>
</Utility>

### Margin
To override the margin value, you can use CSS variables or utilities.

<Utility vMarginTop={16}>
    <CodeSnippetTabs exampleName='nova-flutter-margins'  client:only="react" tabsList= {['CSS variables', 'Utilities']} code={margin} language="dart">
    </CodeSnippetTabs>
</Utility>

### Component-level theming
When overriding only one component or one instance of a component without customizing the whole theme, you can redefine the component variables directly. The following example shows this using a checkbox component. 

<Utility vMarginTop={16}>
    <CodeSnippet isStandalone={true}  exampleName='nova-flutter-component-theming' client:only="react" isTabs={false} code={componentLevelTheming} language="dart">
    </CodeSnippet>
</Utility>

### Variants
For some customization efforts, you may need to update the markup structure or the display properties of the component. To make this easier, we provide examples of some basic variants you can extend to create custom components. Learn more in our [Abstract examples](https://design.visa.com/developing/styles-css/abstracts/action-primary).

&nbsp;

You can also find utility classes that can help you shape your components with [Typography](https://design.visa.com/base-elements/typography), [Flex](https://design.visa.com/base-elements/responsive-grid-system/flex), and [Spacing](https://design.visa.com/base-elements/spacing) examples.


---

# index

---
title: Elevation
tab_title: Code
thumbnail: assets/base-elements/elevation/spatial-model.svg
description: Discover how to use elevation to layer elements and surfaces to create more intuitive and visually appealing interfaces.
meta_description: Discover how to use elevation to layer elements and surfaces to create more intuitive and visually appealing interfaces.
---

## Component Code Examples: elevation

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the elevation component
const component = parsed.components.find(c => c.name === 'elevation');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `elevation`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples


---

# usage

---
title: Elevation
tab_title: Usage
tab_order: 1
description: Discover how to use elevation to layer elements and surfaces to create more intuitive and visually appealing interfaces.
---

Elevation shows the relationships between different surfaces within an application. Consistently mapping elevation levels helps to create an application that mirrors the physical world and feels comfortable and understandable for users.

## Component elevation
Components within each surface layer are mapped to a corresponding elevation level. The diagram below displays the relationship between components and their elevation levels.

<img src="https://design.visa.com/assets/base-elements/elevation/spatial-overview.svg" alt="A diagram comparing the different elevation levels across various components that either use or don't use shadow styling." style={{ backgroundColor: "#ffffff" }}/>

## Shadow specs
Proper use of shadows enhances the visual hierarchy and depth in an application. The chart below lists the shadow values to apply for each elevation level, ensuring consistent and realistic visual effects throughout the application.

Table showing shadow specs

- Layer name: -1
- Elevation: **Shadow 1:** 0, 0, 2 px, 0 rgba(0,0,0,0.10)<br/><br/>**Shadow 2:** 0, 0, 2 px, 0.5 px rgba(0,0,0,0.2)

- Layer name: 0
- Elevation: **Shadow 1:** 0, 0.5 px, 1.5 px, 0 rgba(0,0,0,0.05)

- Layer name: 1
- Elevation: **Shadow 1:** 0, 0.5 px, 1 px, -0.5 px rgba(0,0,0,0.10)<br/><br/>**Shadow 2:** 0, 0.5 px, 1.5 px, 0 rgba(0,0,0,0.10)

- Layer name: 2
- Elevation: **Shadow 1:** 0, 2 px, 7.48 px, -0.5 px rgba(0,0,0,0.08)<br/><br/>**Shadow 2:** 0, 1 px, 2 px, -1 px rgba(0,0,0,0.10)

- Layer name: 3
- Elevation: **Shadow 1:** 0, 5 px, 9 px, -1.5 px rgba(0,0,0,0.10)<br/><br/>**Shadow 2:** 0, 2 px, 3 px, -2 px rgba(0,0,0,0.10)

- Layer name: 4
- Elevation: **Shadow 1:** 0, 10 px, 12.5 px, -2.5 px rgba(0,0,0,0.10)<br/><br/>**Shadow 2:** 0, 2 px, 5 px, 1 px rgba(0,0,0,0.10)

- Layer name: 6
- Elevation: **Shadow 1:** 0, 12.5 px, 25 px, -6 px rgba(0,0,0,0.25)

## Applied in practice
The following is an example page layout with a top navigation, side panel, and dialog box with an accompanying diagram of component elevations (right).

<img src="https://design.visa.com/assets/base-elements/elevation/spatial-model-applied.svg" alt="An example page layout with a top navigation, side panel, and dialog box with an accompanying diagram of component elevations on the right" style={{ backgroundColor: "#ffffff" }}/>


---

# index

---
title: Base elements
meta_description: Discover our system’s visual and architectural standards used to ensure consistent digital experiences. 
page_size: large
description: Discover our system's visual and architectural standards used to ensure consistent digital experiences. 
show_table_of_contents: false
---

<BaseElementsGrid />


---

# breakpoints

---
title: Responsive grid system
description: Use the responsive grid system to organize design elements for visual consistency across pages.
---

## Component Code Examples: breakpoints

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the breakpoints component
const component = parsed.components.find(c => c.name === 'breakpoints');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `breakpoints`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# flex

---
title: Responsive grid system
description: Use the responsive grid system to organize design elements for visual consistency across pages.
---

<CodePage/>

---

# index

---
title: Responsive grid system
tab_title: Usage
description: Use the responsive grid system to organize design elements for visual consistency across pages.
thumbnail: assets/base-elements/responsive-grid-system/responsive-grid-system-graphic.svg
header_image: assets/base-elements/responsive-grid-system/platform-scale-overview.svg
related:
  patterns:
    - application-layouts
---

A responsive grid system is a framework enabling apps and website to adapt their layouts to fit different screen sizes or orientations. This helps ensure visual consistency throughout a product experience while still allowing for flexibility in design.<br/><br/>

VPDS grids guide element placement on a page, working with VPDS components, spacing, and typography. They adjust sizing based on the platform to ensure designs are consistent, usable, and appealing on any screen or device.

## Anatomy
<img src="https://design.visa.com/assets/base-elements/responsive-grid-system/grid-anatomy.svg" alt="A blank webpage with sections identified by letters. A is small white columns on the edges of the screen. B is a series of pink columns at regular intervals across the page. C is small white columns between the pink ones. D is transparent gray boxes that span specific numbers of pink columns."/>

**A. Margin:** The empty space on the two outer edges of the grid. <br/> **B. Column:** Vertical guides spanning the width of the screen. <br/> **C. Gutter:** Empty space between columns with fixed widths based on the defined breakpoints. <br/> **D. Content area:** Area containing page content or components that can span any number of columns. 

## Fixed vs. fluid grids
<div>
    
          
              ### Fixed grids
             
               Fixed grids have a set maximum width with fixed columns and gutters. As the screen size changes, the content areas maintain a fixed width and the margins grow or shrink. They’re ideal for text-heavy designs, enhancing readability.
                      
              <img src="https://design.visa.com/assets/base-elements/responsive-grid-system/grid-fixed.svg" alt="A webpage with the content area, columns and gutters in a fixed width area in the center of the screen with wide margins on both sides."/>
          

          
              ### Fluid grids
           
               Fluid grids scale with screen width, using all the available space. Columns expand as the screen grows, while gutters and margins remain fixed. They’re ideal for dashboards or data-heavy designs. 

              <img src="https://design.visa.com/assets/base-elements/responsive-grid-system/grid-fluid.svg" alt="A webpage where the content area, columns and gutters span almost the entire screen with only small margins on either side."/>         
          
    
</div>

## Breakpoints

Breakpoints are specific points where the layout changes to match different screen sizes. The grid system was designed around the different [Application layouts](https://design.visa.com/patterns/application-layouts) that VPDS offers. Each grid adapts to both the screen width as well as the navigational structure for each layout.

<img src={`https://design.visa.com/assets/base-elements/responsive-grid-system/grid-breakpoints.svg`} alt="Visualization showing >375 there are 4 columns and 16 gutters. 375 to 768 is 8 columns and 16 gutters. 768 to 1024 is 12 columns and 24 gutters. 1024+ is 12 columns and 24 gutters."/>

### Horizontal and advanced layouts

The grid designed for horizontal and advanced layouts is simple and flexible. Its variants are fluid by design with one option for a fixed grid at larger screen sizes. 

<img src="https://design.visa.com/assets/base-elements/responsive-grid-system/grid-horizontal.svg" alt="Two blank screens, one has just a blue header and the other has an additional dark blue bar beneath the blue header."/>

Breakpoints for horizontal navs, which lists the  number of columns, margins, and gutters

- Breakpoint: 4
- Number of columns: 16px
- Margins: 16px

- Breakpoint: 8
- Number of columns: 16px
- Margins: 24px

- Breakpoint: 12
- Number of columns: 24px
- Margins: 24px

- Breakpoint: 12
- Number of columns: 80px min
- Margins: 24px

### Vertical and mixed layouts

The grid designed for vertical and mixed layouts adapts to accommodate the left navigation panel. The grid begins to the right of the left navigation, with the space between the navigation panel and the first column serving as the left margin. While the grid system is fixed in Figma, it can also be built as fluid. 

<img src="https://design.visa.com/assets/base-elements/responsive-grid-system/grid-vertical.svg" alt="Two blank screens, one only has a dark blue bar on the left, the other has both the dark blue left bar and a blue header."/>

Breakpoints for vertical and mixed layouts, which lists the number of columns, margins, and gutters

- Breakpoint: 12
- # columns: 24px
- Margins: 24px

- Breakpoint: 12
- # columns: 24px
- Margins: 24px

- Breakpoint: 12
- # columns: 32px
- Margins: 24px

- Breakpoint: 12
- # columns: 32px
- Margins: 24px

- Breakpoint: 12
- # columns: 32px
- Margins: 24px

- Breakpoint: 12
- # columns: 32px
- Margins: 24px

- Breakpoint: 12
- # columns: 32px
- Margins: 24px

- Breakpoint: 12
- # columns: 32px
- Margins: 24px

## System baseline

A baseline grid ensures consistency within content areas across platforms. It guides the design of foundational elements like typography and iconography, as well as main components.

### Factors of four

The VPDS grid system is based on factors of four as the base unit. For example, for vertical spacing, it is suggested to use spacing blocks of 16px, 24px, 32px, 48px, etc.<br/><br/>

**Note:** Aligning to half pixels and using odd numbers may disrupt clean pixel alignment.

<img src="https://design.visa.com/assets/base-elements/responsive-grid-system/grid-system-baseline.svg" alt="Two text input fields side by side with highlights showing they are 16px apart from each other and 24px above a Submit button"/>

## Content reflow
As screen width changes, consider how your content areas will shift or reflow. It's crucial to communicate this reflow to the development team, ensuring they understand how the design should adapt at each breakpoint. Reflow can be defined in terms of percentages or column spanning. For instance, if a content area occupies 50% (6 columns) at 1600px, it might occupy 25% (4 columns) at 1280px. Define your reflow patterns based on the components within your content areas.

## Screen size
The VPDS grid system is designed to scale across multiple platforms, from mobile to ultra-wide screens. Each view is designed for seamless content scaling. Note the grid dimension changes from mobile to desktop: Margins increase from 16px to 24px, and the number of columns changes with screen width. Mobile components fit easily into the predefined mobile grid.

### Example layouts
The following is an example of a form designed in both web and mobile. 

### Web

<img src="https://design.visa.com/assets/base-elements/responsive-grid-system/platform-examples-web.svg" alt="A form in web view, with a full header that has a logo, application name, tabs, and menu drop downs."/>

### Mobile

<img src="https://design.visa.com/assets/base-elements/responsive-grid-system/platform-examples-mobile.svg" alt="A form in mobile view, the UI and text are larger and constrained to the narrower width and there is a smaller header with only a logo, menu and profile buttons."/>

## Component size

         
          ### Web scale
            Web components have a base height of 38 dp. The default component size is determined across the system by the base height.
            {/* no alt because the image doesn't give info not in paragraph */}
            <img src="https://design.visa.com/assets/base-elements/responsive-grid-system/platform-component-web.svg" alt=""/>
      
         
          ### Mobile scale
            The mobile scale is 1.25 times larger than web, with a base height of 46 dp. It’s applied for native mobile and responsive web views when a touch device is detected.
            {/* no alt because the image doesn't give info not in paragraph */}
            <img src="https://design.visa.com/assets/base-elements/responsive-grid-system/platform-component-mobile.svg" alt=""/>
      

## Typography size
Typography also scales up for mobile platforms. Body 2 is the base body copy size for the design system. Body 2 is defined as 14 px for web platforms and 16 px for mobile platforms. Get more detailed specifications in [Typography.](https://design.visa.com/base-elements/typography/usage)

<img src="https://design.visa.com/assets/base-elements/responsive-grid-system/responsive-grid-type-ramp.svg" alt="Two side by side columns showing the difference in text between web and mobile. Mobile is larger and the text wraps to the next line earlier than web."/>

## Units
Not all screens and platforms have the same pixel density, which is the number of pixels in a given area. This results in elements appearing larger on screens with lower pixel density and smaller on screens with higher density.<br/><br/>

To address this, iOS uses points (pts) to determine the pixel density of Apple devices. Android uses density-independent pixels (dps) to scale designs uniformly across all screens. A density-independent pixel uses a physical pixel on a screen with a density of 160 pixels per inch as the base.
<br/>

Unit usage and operating system

- Unit: Android

- Unit: Image resolution

- Unit: iOS

- Unit: Web

- Unit: Type scaling



---

# index

---
title: Size and shape
side_nav_title: Size and shape
thumbnail: assets/base-elements/size-and-shape/size-and-shape-graphic.svg
description: Find examples and classes for defining the dimensions and shape of elements in your designs.
---

## Component Code Examples: sizes

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the sizes component
const component = parsed.components.find(c => c.name === 'sizes');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `sizes`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples


---

# index

---
title: Spacing
side_nav_title: Spacing
thumbnail: assets/base-elements/spacing/spacing-graphic.svg
description: Access resources to ensure consistent spacing between, outside, and within digital elements.
meta_description: Access resources to ensure consistent spacing between, outside, and within digital elements.
---

## Component Code Examples: spacing

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the spacing component
const component = parsed.components.find(c => c.name === 'spacing');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `spacing`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# index

---
title: States
tab_title: Code
description: Consistently apply visual cues and design patterns to communicate a component’s interaction state.
thumbnail: assets/base-elements/states/states-graphic.svg
header_image: assets/base-elements/states/states-overview.svg
---

## Flutter widget state

Flutter Widget State is used to manage the state of a widget and its lifecycle. For more details, refer to the official [WidgetState Documentation](https://api.flutter.dev/flutter/widgets/WidgetState.html).

### Additional widget state resources

<div class="v-flex v-flex-col v-row-gap-4">
[Widget Lifecycle](https://docs.flutter.dev/ui/interactivity#the-widget-lifecycle)
[Stateful and Stateless Widgets](https://docs.flutter.dev/ui/interactivity#stateful-and-stateless-widgets)
</div>
## State management

State management is the process of handling the state of an application to ensure it behaves as expected and remains responsive to user interactions. It's crucial in Flutter to ensure the UI updates correctly when the state changes.

### Additional state management resources

<div class="v-flex v-flex-col v-row-gap-4">
[Managing State in Flutter](https://docs.flutter.dev/data-and-backend/state-mgmt/intro)
[Flutter State Management Options](https://docs.flutter.dev/data-and-backend/state-mgmt/options)
[Flutter State Management Guide](https://docs.flutter.dev/data-and-backend/state-mgmt)
</div>

---

# usage

---
title: States
tab_title: Usage
description: Consistently apply visual cues and design patterns to communicate a component’s interaction state.
thumbnail: assets/base-elements/states/states.svg
header_image: assets/base-elements/states/states-overview.svg
---

States are visual cues and design patterns that are consistently applied to components to help the user better understand the interaction. States include default, hover, focus, and more.

## Anatomy

<img src="https://design.visa.com/assets/base-elements/states/states-anatomy.svg" alt="Buttons, chips, and tabs shown in their different interaction states" aria-describedby='anatomy-image-description'/>
<p id="anatomy-image-description" class="v-sr">Three sections showing states. Section A shows a default button state is blue, active hover is brighter, focused with a keyboard is brighter and has an extra dotted border, pressed is dark blue, and disabled is gray. The same states are shown again with a white or transparent button, with hover, keyboard focus, and pressed all having a light blue fill. Section B shows a selected chip is blue with a white checkmark. Section C shows three tabs with the first tab active. The active tab has a light gray background and blue line underneath the text.</p>
<div style={{marginBlockStart: "16px"}}>
**A. Color:** Value of the active and surface color that adjusts based on the component state. <br/>
**B. Icon:** Visual indicator communicating the selected state. <br/>
**C. Active indicator line and text:** Line used to indicate the selected view, with text changing to bold when active.
</div>

## Component states

Component states support user interactions and guide visual design expectations. Not all components will have all of the following states. 

    
          
              ### Default

              The default, enabled state for all interactive elements and components.
              <img src="https://design.visa.com/assets/base-elements/states/states-default.svg" alt="Default state examples are an input field with a gray border and label above it. A transparent rectangular button with blue text and border. Another button is a blue circle with a yellow and white icon and black label below it. Two chips, one white with blue text and border and the other blue with white text and checkmark." />
              
          

          
              ### Hover

              The state when the mouse pointer is placed over the component. Not used on touch devices.
              <img src="https://design.visa.com/assets/base-elements/states/states-hover.svg" alt="Hover state examples are the input field's gray border has changed to blue. Rectangular button is now filled with light blue. Icon button is lighter with blue label text instead of black. The white chip is now has a light blue fill while the selected chip is unchanged."/> 
                       
          
    

    
          
              ### Pressed
              
              The temporary state indicating a component is being tapped, clicked with a mouse, or triggered with a keyboard.
              <img src="https://design.visa.com/assets/base-elements/states/states-pressed.svg" alt="Pressed examples are input field's gray border has changed to blue and has text insert caret. Rectangular button is now filled with light blue, border and label are dark blue and text is bold. Icon button is darker with blue label text instead of black. The chips are both darker but otherwise unchanged."/>
              
          

          
              ### Focus (keyboard)

              The state indicating an interactive component is in-focus during keyboard or voice-activated navigation.
              <img src="https://design.visa.com/assets/base-elements/states/states-focus.svg" alt="Keyboard focus examples have all controls appear the same as the hover state except a text insert caret is in the input field and an additional dotted border appears around all."/> 
                      
          
    

    
          
              ### Focus (mouse)

              The state indicating an input field has been clicked into and is currently in-focus. This isn’t used for any other components. 
              <img src="https://design.visa.com/assets/base-elements/states/states-focus-mouse.svg" alt="Mouse focus examples are an input field with blue label text, border, and text input caret."/>
              
          

          
              ### Active

              The state indicating the currently selected item out of a set, menu, or list. 
              <img src="https://design.visa.com/assets/base-elements/states/states-active.svg" alt="Active example is a list of options in a menu. The first option has a gray background and blue line to the left of the option text."/> 
                        
          
    

    
          
              ### Selected (on/off)

              The state showing the user’s selection, usually from a list of options, a checkbox, or a setting.
              <img src="https://design.visa.com/assets/base-elements/states/states-selected.svg" alt="Selected on off examples are switch button has dark blue background and a white circle on the right side. Checkbox is filled in with blue and has a white checkmark."/>
              
          

          
              ### Disabled

              The inactive state of a component, indicating the action is not available and can’t be interacted with. 
              <img src="https://design.visa.com/assets/base-elements/states/states-disabled.png" alt="Disabled examples are input field, rectangular and icon buttons, and chips have all light gray colors and text. The input field has a dotted border instead of a solid line."/> 
                       
          
    

    
          
              ### Read-only

              An inactive state which may show possible or past interactions, or the absence of editing rights.
              <img src="https://design.visa.com/assets/base-elements/states/states-read-only.png" alt="Read-only example is input field has black text and label but a dotted border instead of a solid line."/>
              
          

          
              ### Expanded

              State indicating that a component is expanded, with the menu arrow pointing up. 
              <img src="https://design.visa.com/assets/base-elements/states/states-expanded.svg" alt="Expanded example is menu with expandable options. The first option is expanded, shown by a chevron pointing up and two options shown below. The last option is collapsed, shown by a chevron pointing down."/> 
                         
          
    

    
          
              ### Error

              State that uses color and an icon with text to indicate an error and provide user guidance.
              <img src="https://design.visa.com/assets/base-elements/states/states-error.svg" alt="Error example is input field has red label text, border, and error text below the field. Preceding the error text is a red icon that is a circle with an exclamation mark inside."/>
              
          
    

## Interactive target areas
Ensuring sufficient space around interactive areas is vital as it facilitates easier interaction, particularly for users who may struggle with precise movements. When using components with smaller visual footprints, it's important to design with ample touch area in mind and avoid placing elements too closely together.

### Touch targets

Use the minimum size of 44 x 44 dps for touch areas across all interactive components.

<div className="resize_mobile">
    <img src="https://design.visa.com/assets/base-elements/states/states-touch-targets.svg" alt="Mobile UI icon button with 44dp by 44dp measurements"/>
</div>

For additional context, learn more about challenges faced by [users with a limited ability to use a mouse](https://www.w3.org/WAI/people-use-web/user-stories/#reporter).

### Non-touch targets

- Use the minimum size of  24 x 24 dps for touch areas across all interactive components.
- Rounded corners detract from 24 x 24 target.
- To learn more about accessibility minimum targets, refer to [WCAG guidance](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html).

<div className="resize_mobile">
    <img src="https://design.visa.com/assets/base-elements/states/states-non-touch.svg" alt="A UI icon button with a touch target of less than 24 x 24 dps. "/>
</div>

---

# index

---
title: Surface
description: Use these generic styles to define the layout and visual hierarchy of your app with surface components, or customize and create your own components.
thumbnail: assets/base-elements/surface/surfaces-graphic.svg
---

## Component Code Examples: surface

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the surface component
const component = parsed.components.find(c => c.name === 'surface');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `surface`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples


---

# accessibility

---
title: Typography
tab_title: Accessibility
tab_order: 2
description: Get guidance, examples, and code to enhance readability through consistent text styles and hierarchy.
meta_description: Get code to enhance accessibility through consistent text styles and hierarchy. 
thumbnail: assets/base-elements/typography/typography.svg
header_image: assets/base-elements/typography/typography-overview.svg
---

Creating access for everyone, everywhere requires attention to accessibility attributes, best practices, and requirements. Find accessibility guidance below.

## Best practices
- Avoid using pure visual styles to convey structural knowledge or indicate relative importance.
- Ensure a color contrast ratio of at least 4.5:1 for text, informational images, and images of text to their backgrounds. For text that is 18 point or 14 point bold or larger, maintain a ratio of 3:1.

### Text spacing
In content implemented using markup languages that support the following text style properties (user agent default styles, author styles, user styles), ensure no loss of content or functionality by setting all of the following without changing any other style property:
- Set line height (line spacing) to at least 1.5 times the font size.
- Set spacing following paragraphs to at least 2 times the font size.
- Set letter spacing (tracking) to at least 0.12 times the font size.
- Set word spacing to at least 0.16 times the font size. 
<br/>

**Note**: For human languages and scripts that do not use one or more of these text style properties, conform using only the properties available for that language and script combination.

### All capitals
There are no specific WCAG guidelines on the use of ALL CAPS. Opinions vary on their use among users with cognitive disabilities, non-sighted, and low vision. The style guide in the content foundation recommends using sentence case (capitalizing the first letter of each title, label, phrase, or sentence, while still capitalizing proper nouns). 

#### Cognitive disabilities

Users with cognitive disabilities might find it difficult to read due to indistinct word shapes instead of distinctive word shapes. For instance, compare the word shape of "CONTACT US" to "Contact Us."

#### Non-sighted

Screen readers announce text letter-by-letter only when a word cannot be formed from the combinations of letters. For example, a screen reader may read the uppercase text "CONTACT US" as "Contact U. S." because it interprets the uppercase "US" as an acronym for "United States."

#### Low-vision

Users with visual impairments might find words in all capitals more legible when zoomed in or viewed from a distance, as ALL CAPS appears relatively larger in font size than normal text.



---

# index

---
title: Typography
tab_title: Code
description: Get guidance, examples, and code to enhance readability through consistent text styles and hierarchy.
meta_description: Get code to enhance readability through consistent text styles and hierarchy. 
thumbnail: assets/base-elements/typography/typography.svg
header_image: assets/base-elements/typography/typography-overview.svg

---

## Component Code Examples: typography

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the typography component
const component = parsed.components.find(c => c.name === 'typography');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `typography`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples


---

# usage

---
title: Typography
tab_title: Usage
tab_order: 1
description: Get guidance, examples, and code to enhance readability through consistent text styles and hierarchy.
meta_description: Learn how to enhance readability through consistent text styles and hierarchy. 
thumbnail: assets/base-elements/typography/typography.svg
header_image: assets/base-elements/typography/typography-overview.svg
related: 
  content: 
    - readability
  baseElements:
    - design-tokens/overview
---

We created a new humanistic typeface, Visa Dialect, designed specifically for our brand. Its foundation is built on our core brand attributes: accessible, inclusive, and approachable. It's modern, but still feels like it has been crafted by the human hand. It has been designed to be approachable, unique, and easily read on any device. <br/><br/>

Visa branded digital experiences use Visa Dialect UI. Visa Dialect UI has been created specifically for user interfaces. It has narrower forms than Visa Dialect and has been designed to be highly efficient for small typographic settings.<br/><br/>

Internal users can access Visa Dialect UI on [Sharepoint (internal only)](https://bookmarks.visa.com/vpds-sharepoint)<!-- aria-label="Sharepoint (internal only, opens in a new tab)" -->.<br/><br/>

For digital experiences that are not Visa branded, font choice can vary as needed, but should not be Visa Dialect. Mobile applications may be best suited to use native fonts based on platform, to take advantage of built in features. For browser based applications, we recommend Open Sans, which is from Google's Open Fonts Directory.

## Type ramp
For this ramp, there are type categories built in to support and simplify usage. While applying the styles, keep in mind the typographic hierarchy set in place and the intended use for each type style. 

### Headlines
The headline category is meant for page and section titles. Display 1 and 2 are intended for banner areas and landing pages, and may not be suitable for use across a whole application.
- Start most page designs with Headline 1 as your largest headline size. 
- Use typography with a line height about 1.3x the size of the text, referred to as 'line-height-short' in the system.
- Use sentence case.
- Avoid adding punctuation such as periods, commas, colons, or semicolons unless completing sentences or for impact. 

Heading measurements, font, and levels

- Label: **Size/line height:** 60 px/78 px <br/><br/> **Paragraph spacing:** 0px
- Web: **Size/line height:** 70 px/91 px <br/><br/> **Paragraph spacing:** 0px
- Mobile: 0px
- Letter spacing: Semibold/ 600
- Weight: H1

- Label: **Size/line height:** 48 px/62 px <br/><br/> **Paragraph spacing:** 0px
- Web: **Size/line height:** 58 px/75 px <br/><br/> **Paragraph spacing:** 0px
- Mobile: 0px
- Letter spacing: Semibold/ 600
- Weight: H1, H2

- Label: **Size/line height:** 32 px/42 px <br/><br/> **Paragraph spacing:** 0px
- Web: **Size/line height:** 36 px/47 px <br/><br/> **Paragraph spacing:** 0px
- Mobile: 0.5px
- Letter spacing: Semibold/ 600
- Weight: H1, H2

- Label: **Size/line height:** 25 px/33 px <br/><br/> **Paragraph spacing:** 0px
- Web: **Size/line height:** 28 px/36 px <br/><br/> **Paragraph spacing:** 0px
- Mobile: 0px
- Letter spacing: Medium/ 500
- Weight: H1-H3

- Label: **Size/line height:** 20 px/26 px <br/><br/> **Paragraph spacing:** 0px
- Web: **Size/line height:** 24 px/31 px <br/><br/> **Paragraph spacing:** 0px
- Mobile: 0px
- Letter spacing: Semibold/ 600
- Weight: H2-H5

- Label: **Size/line height:** 18 px/24 px <br/><br/> **Paragraph spacing:** 0px
- Web: **Size/line height:** 22 px/29 px <br/><br/> **Paragraph spacing:** 0px
- Mobile: 0px
- Letter spacing: Semibold/ 600
- Weight: H2-H5

- Label: **Size/line height:** 16 px/21 px <br/><br/> **Paragraph spacing:** 0px
- Web: **Size/line height:** 18 px/23 px <br/><br/> **Paragraph spacing:** 0px
- Mobile: 0px
- Letter spacing: Semibold/ 600
- Weight: H3-H6

- Label: **Size/line height:** 16 px/21 px <br/><br/> **Paragraph spacing:** 0px
- Web: **Size/line height:** 18 px/23 px <br/><br/> **Paragraph spacing:** 0px
- Mobile: 0px
- Letter spacing: Medium/ 500
- Weight: H3-H6

- Label: **Size/line height:** 14 px/18 px <br/><br/> **Paragraph spacing:** 0px
- Web: **Size/line height:** 16 px/21 px <br/><br/> **Paragraph spacing:** 0px
- Mobile: 0px
- Letter spacing: Semibold/ 600
- Weight: H3-H6

- Label: **Size/line height:** 10 px/13 px <br/><br/> **Paragraph spacing:** 0px
- Web: **Size/line height:** 11 px/14 px <br/><br/> **Paragraph spacing:** 0px
- Mobile: 1px
- Letter spacing: Semibold/ 600
- Weight: H2-H6

### Overline
- Pair overline headlines with display, headline, or subtitle content. These are sometimes called an eyebrow or category.
- Use all caps for overline headlines, containing no periods, commas, colons, or semicolons after sentence fragments, and limit to 1–3 words.

### Body
The body category is meant for paragraph styling for the main content areas of your page. Most applications will use Body 2 as the default body copy styling, and doing so will ensure proper relationship between the content of your page and the design system components. <br/>
- To increase readability, typography in this category uses a line height about 1.5x the size of the text. We define this is ‘line-height-default’ in the system. 
- Body 1, 2, and 3 should always use sentence case and all standard punctuation.

Body text measurements, weight, and tags

- Label: **Size/line height:** 16 px/24 px <br/><br/> **Paragraph spacing:** TBD
- Web: **Size/line height:** 18 px/27 px <br/><br/> **Paragraph spacing:** TBD
- Mobile: 0px
- Letter spacing: Regular/ 400
- Weight: p, span

- Label: **Size/line height:** 14px/ 22px <br/><br/> **Paragraph spacing:** 16px
- Web: **Size/line height:** 16px/ 24px <br/><br/> **Paragraph spacing:** 16px
- Mobile: 0px
- Letter spacing: Regular/ 400
- Weight: p, span/ document/ body default

- Label: **Size/line height:** 14px/ 22px <br/><br/> **Paragraph spacing:** TBD
- Web: **Size/line height:** 16px/ 24px <br/><br/> **Paragraph spacing:** 16px
- Mobile: 0px
- Letter spacing: Semibold/ 600
- Weight: body, default

- Label: **Size/line height:** 14px/ 22px <br/><br/> **Paragraph spacing:** 12px
- Web: **Size/line height:** 16px/ 24px <br/><br/> **Paragraph spacing:** 12px
- Mobile: 0px
- Letter spacing: Regular/ 400
- Weight: ul, li

- Label: **Size/line height:** 14px/ 22px <br/><br/> **Paragraph spacing:** 16px
- Web: **Size/line height:** 16px/ 24 px <br/><br/> **Paragraph spacing:** 16px
- Mobile: 0px
- Letter spacing: Medium/ 500
- Weight: ——

- Label: **Size/line height:** 14px/ 22px <br/><br/> **Paragraph spacing:** 16px
- Web: **Size/line height:** 16px/ 24px <br/><br/> **Paragraph spacing:** 16px
- Mobile: 0px
- Letter spacing: Medium/ 500
- Weight: ——

- Label: **Size/line height:** 12px/ 18px <br/><br/> **Paragraph spacing:** 16px
- Web: **Size/line height:** 14px/ 21px <br/><br/> **Paragraph spacing:** TBD
- Mobile: 0px
- Letter spacing: Regular/ 400
- Weight: p, span

### Ordered and unordered lists

#### Ordered lists

<div className="text-like-image">
<ol>
<li>Item 1 - with enough words to make a text wrap, so paragraph spacing is apparent.</li>
<li>Item 2</li>
<li>Item 3</li>
</ol>
</div>
Use ordered lists when the sequence of the items is important, such as step-by-step instructions. 

#### Unordered lists

<div className="text-like-image">
<ul>
<li>Item 1 - with enough words to make a text wrap, so paragraph spacing is apparent.</li>
<li>Item 2</li>
<li>Item 3</li>
</ul>
</div>
Use unordered lists when the sequence is not important.

### Detail
Typography in the detail category is applied to the interactive components in the design system. 
- Use typography with a line height about 1.3x the size of the text, defined as "line-height-short" in the system.
- Use UI label large for tables, tabs, and navigation; it matches Body 2.
- Use UI label for labels on input fields and form elements.
- Use UI label small for labels on icon buttons.

Button and label measurements, spacing, and weight

- Label: **Size/line height:** 14px/ 18px <br/><br/> **Paragraph spacing:** 0px
- Web: **Size/line height:** 16px/ 22px <br/><br/> **Paragraph spacing:** 0px
- Mobile: 0.25px
- Letter spacing: Semibold/ 600

- Label: **Size/line height:** 12px/ 16px <br/><br/> **Paragraph spacing:** 0px
- Web: **Size/line height:** 14px/ 18px <br/><br/> **Paragraph spacing:** 0px
- Mobile: 0.25px
- Letter spacing: Semibold/ 600

- Label: **Size/line height:** 12px/ 16px <br/><br/> **Paragraph spacing:** 0px
- Web: **Size/line height:** 14px/ 18px <br/><br/> **Paragraph spacing:** 16px
- Mobile: 0.25px
- Letter spacing: Medium/ 500

- Label: **Size/line height:** 14px/ 18px <br/><br/> **Paragraph spacing:** 12px
- Web: **Size/line height:** 16px/ 20px <br/><br/> **Paragraph spacing:** 0px
- Mobile: 0px
- Letter spacing: Regular/ 400

- Label: **Size/line height:** 14px/ 18px <br/><br/> **Paragraph spacing:** 12px
- Web: **Size/line height:** 16px/ 20px <br/><br/> **Paragraph spacing:** 0px
- Mobile: 0px
- Letter spacing: Medium/ 500

- Label: **Size/line height:** 12px/ 16px <br/><br/> **Paragraph spacing:** 0px
- Web: **Size/line height:** 14px/ 18px <br/><br/> **Paragraph spacing:** 0px
- Mobile: 0px
- Letter spacing: Regular 400

- Label: **Size/line height:** 12px/ 16px <br/><br/> **Paragraph spacing:** 0px
- Web: **Size/line height:** 14px/ 18px <br/><br/> **Paragraph spacing:** 0px
- Mobile: 0px
- Letter spacing: Medium/ 500

- Label: **Size/line height:** 11px/ 14px <br/><br/> **Paragraph spacing:** 0px
- Web: **Size/line height:** 12px/ 16px <br/><br/> **Paragraph spacing:** 0px
- Mobile: 0px
- Letter spacing: Regular/ 400

## Applying the type ramp
When using the type ramp to build an interface, it is recommended not to modify or change properties such as weight, size, and color for any type style. Each type style has been selected with consideration for user needs and systemization within the overall design system.

## Hierarchy
Effective typographic hierarchy makes content easy to consume and understand. It enhances scan-ability and guides users on what information to focus on first. Use it as a tool to direct the reader’s attention to the content in the desired order. 

<div className="text-like-image-hierarchy">
  <ul>
    <li>
      <span>Headline 2 &lt;h2&gt;</span>
      <span>Financial inclusion</span>
    </li>
    <li>
      <span>Headline 3 &lt;h3&gt;</span>
      <span>What is Financial inclusion?</span>
    </li>
    <li>
      <span>Body 2</span>
      <span><Typography variant="body-2">No barriers between you and the financial services you need to survive and thrive.</Typography></span>
    </li>
    <li>
      <span>Subtitle 1 &lt;h4&gt;</span>
      <span>Where we focus our efforts</span>
    </li>
    <li>
      <span>Body 2</span>
      <span><Typography variant="body-2">We’re using the power of our network to create new solutions, stimulate investment and innovation, promote usage, and encourage strong enabling environments, from China to Colombia, Africa to America.</Typography></span>
    </li>
  </ul>
</div>

### Consistent appearance

Maintain a consistent appearance for text within the same category.

### Sentence case

Use sentence case, as Visa adopts this in nearly all scenarios.

## Text alignment
There are three options for text alignment: right-aligned, center-aligned, and left-aligned.

### Right-aligned

Right-align text for side notes or visual grouping.
<img src="https://design.visa.com/assets/base-elements/typography/type-right-align.svg" alt="Webpage showing mock notation text that is all aligned against a line to the right of the text."/>

### Center-aligned

Center-align text for copy in UI elements such as buttons.
<img src="https://design.visa.com/assets/base-elements/typography/type-center-align.svg" alt="Button with the label Continue center-aligned"/>

### Left-aligned

Left-align text for product copy. This is most common in left-to-right-languages.
<img src="https://design.visa.com/assets/base-elements/typography/type-left-align.svg" alt="Webpage showing mock paragraph text that is all aligned against a line to the left of the text."/>

## Paragraph spacing
Spacing between paragraphs can affect how users perceive relationships between information. Keep paragraph spacing between 0.75 and 1.25 times your font size. In Microsoft Word, this equates to a full line of spacing between paragraphs.

## Line height
Line height, also known as leading, is the space between baselines in a block of text. It measures the distance from the bottom of one line of text to the bottom of the next. <br/><br/>
We recommend a line height approximately 1.5 times the font size, translating to 1.5 line spacing in Microsoft Word. On iOS, this is measured in pixels (px), and on Android, in density-independent pixels (dp).

## Line length
The ideal line length is around 50-75 characters, including spaces, or 12-14 words per line. Longer lines of text can feel intimidating and overwhelming to users, potentially leading them to avoid reading. Conversely, lines that are too short disrupt the reader’s rhythm by requiring frequent eye movements.

<img src="https://design.visa.com/assets/content/readability/readability-line-length.svg" alt="A scale from 0-105 characters showing 3 parargraphs- one at the 50 character mark, one at the 75 character mark, and one going past the 105 character mark. The paragraph at the 75 mark has a green check mark next to it while the other two paragrpahs have red x's."/>

Table adapted from the [Baymard Institute](https://baymard.com/blog/line-length-readability)<!-- aria-label="Baymard Institute (opens in a new tab)" -->.

## Language considerations
Visa Dialect has a vast Latin and Cyrillic character set, making it suitable for many languages. For languages not supported by Visa Dialect, we use [Noto Sans](https://fonts.google.com/noto)<!-- aria-label="Noto Sans (opens in a new tab)" -->, a free font available from Google.
<br/>
Languages vary in average word lengths and heights, which can affect typography layout. When internationalizing our typeface, consider the differences in word length, alignment, height, and language categories. Reference [Material’s guidance](https://m2.material.io/design/typography/language-support.html#language-considerations)<!-- aria-label="Material’s guidance (opens in a new tab)" --> regarding language support for more information.


---

# accessibility

---
title: Accordion
tab_order: 2
description: Sets of vertical headers that reveal or hide subsections of content.
meta_description: Find accessibility guidelines for vertically stacked headers that expand and collapse related content panels. 
thumbnail: assets/components/accordion-graphic.svg
---

## Best practices

<br/>
**Note:** VPDS uses native HTML `details` and `summary` elements.
- Use descriptive accordion titles that reflect the content within the associated panels.
- Check that the icons in the accordion header use the library’s right-to-left class if needed.

## Keyboard controls

Keyboard actions and their corresponding behaviors for accordion

- Key: Moves focus to the next focusable element. All focusable elements in the accordion section are included in the tab sequence.

- Key: Moves focus to previous focusable element. All focusable elements in accordion section included in tab sequence.

- Key: Expands or collapses the section panel when focus is on the accordion's header.



---

# index

---
title: Accordion
tab_title: Code
thumbnail: assets/components/accordion-graphic.svg
description: Sets of vertical headers that reveal or hide subsections of content. 
meta_description: Get code for vertically stacked headers that expand and collapse related content panels. 
categories:
  - structure-and-layout
---

## Component Code Examples: accordion

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the accordion component
const component = parsed.components.find(c => c.name === 'accordion');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `accordion`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Accordion
tab_title: Usage
tab_order: 1
description: Sets of vertical headers that reveal or hide subsections of content. 
meta_description: Learn how to use vertically stacked headers that expand and collapse related content panels. 
keywords: ["Summary (html)", "expand/collapse", "hide/show"]
related: 
  components: 
    - content-card
    - checkbox
    - tabs
  patterns:
    - wizard
---

Accordions are vertically stacked sections of content that, when selected, expand or collapse to reveal or conceal related content panels. They’re a type of progressive disclosure that simplify large amounts of content and minimize scrolling. 
<br />
Also known as: Summary (html), expand/collapse, hide/show.

## Anatomy
<img src="https://design.visa.com/assets/components/accordion/accordion-anatomy.svg" alt="An accordion with callout A indicating the required chevron, callout B indicating the required header section, and callout C indicating the required panel"/>

**A. Chevron (required):** Interactive element indicating that users can expand or collapse the accordion. <br/> **B.  Header section (required):** Area containing the accordion title which briefly describes the content in the expanded panel. <br/> **C. Panel (required):** Area containing content that, when expanded, provides details relevant to the header.

## Usage

When to use and when not to use different types of accordions

- Component: To present users with multiple sections of content that can be expanded simultaneously. This is the most common use case.
- When to use: To organize content into clear, distinct categories where only one category should be viewed at a time. Use single-select accordion instead. <br/><br/>
            If there is not enough content to warrant condensing. Add this content to the main content area of the page instead. <br/><br/> To organize large volumes of content into separate, distinct categories. Use [Tabs](https://design.visa.com/components/tabs/usage) instead. <br/><br/> To provide a visual summary of information. Use a [Content card](https://design.visa.com/components/content-card/usage) instead.

- Component: To present users with multiple sections of content, but only one can be expanded or viewed at a time.
- When to use: If users would benefit from viewing information between multiple sections simultaneously. Use a multi-select accordion instead. <br/><br/>For complex, step-by-step tasks. Use a [Wizard](https://design.visa.com/patterns/wizard/usage) instead.<br/><br/>To provide a visual summary of information. Use a [Content card](https://design.visa.com/components/content-card/usage) instead.

## Best practices
- Use accordions carefully as they diminish content visibility and increase interaction cost.
- Never hide critical information that should be easily accessible within an accordion. 
- Enhance usability by making the header section clickable for content expansion.

### Multi-select accordions
Multi-select accordions provide users with control over how they view the information by allowing them to expand multiple sections of content at once. They are typically used for FAQs, product descriptions, and event or course details.
<img src="https://design.visa.com/assets/components/accordion/accordion-multi.svg" alt="A frequently asked questions section with multiple accordions expanded to show content."/>
- Allow users to reference or compare multiple sections of content at the same time. 
- Place in logical locations to maintain the natural flow of the page, ensuring they’re easy to find and use.

### Single-select accordions
Single-select accordions only allow users to view one section of content at a time. They are ideal for small screen sizes as they minimize clutter and focus user attention on specific content. Learn more in [Platform considerations](https://design.visa.com/components/accordion/usage/#platform-considerations).
<img src="https://design.visa.com/assets/components/accordion/accordion-single.svg" alt="A frequently asked questions section displayed in a mobile layout with only one accordion opened at a time."/>
- Use single-select accordions sparingly as they reduce user control and can lead to frustration.
- Position single-select accordions logically to preserve page flow, ensuring easy discovery and interaction.

#### Automatic closure

Single-select accordions only allow users to expand one section at a time. The expanded section should automatically collapse when the user selects a new section. 
<img src="https://design.visa.com/assets/components/accordion/accordion-auto-close.svg" alt="An accordion layout with only one accordion expanded at a time"/>
- Ensure users also have the ability to control when they want to close a section and open another. 

### Chevron direction
Visually differentiate expanded and collapsed sections using the chevron direction. In some cases, it may be appropriate to use a plus (+) or minus (-) icon instead of a chevron. Whichever method you choose, use it consistently.  

#### Collapsed

Collapsed sections should use the inactive color palette.
<img src="https://design.visa.com/assets/components/accordion/accordion-chevron-collapse.svg" alt="Collapsed accordions with the chevron pointing to the right and the header text in black."/>
- Use the right pointing chevron to indicate collapsed content can be expanded.
- Use the plus (+) icon to indicate that the section can be expanded.

#### Expanded

Expanded sections should use the active color palette.
<img src="https://design.visa.com/assets/components/accordion/accordion-chevron-expand.svg" alt="An expanded accordion with the chevron pointing down and the header text in active blue."/>
- Use the downward pointing chevron to indicate expanded content can be collapsed.
- Use the minus (-) icon to indicate that the section can be collapsed. 

## Behaviors
### Applying accordion functionality
In some cases, it may be appropriate to combine interactive elements to achieve accordion-like functionality. Unlike standard accordions that only reveal or conceal content, these combinations can be used to show or hide additional user options or actions. This functionality can be accomplished using a UI icon button or text button to expand or collapse the section. Keep in mind that these combinations have different accessibility considerations than single- and multi-select accordions. 

#### Revealing a checkbox group

Accordion functionality can be used to expand or collapse additional options within a checkbox group. This is achieved by combining a UI icon button with checkbox group, where selecting the chevron would show or hide additional, nested options. This design requires careful consideration as it introduces a two-step process which can add confusion for users.

##### Collapsed

The user selects the chevron button to reveal the options within the checkbox group.
<img src="https://design.visa.com/assets/components/accordion/accordion-checkbox-collapse.svg" alt="A collapsed checkbox group titled 'All products' with the chevron pointing to the right."/>
- Ensure the checkbox is visible when the accordion is collapsed to indicate there's an action to be taken.
- Use the right pointing chevron to indicate collapsed content. 

##### Expanded

The user makes their selection from the available options within the checkbox group.
<img src="https://design.visa.com/assets/components/accordion/accordion-checkbox-expanded.svg" alt="An expanded checkbox group titled 'All products' with the chevron pointing down to display checkboxes for 'Credit offers', 'Retirement plans', and 'Auto loans' under 'All products'."/>
- Group related options and order them logically by either the order of importance or alphabetically.
- Use the downward pointing chevron to indicate expanded content. 

#### Revealing a panel

Accordion functionality can be used to expand or collapse a panel through a button. For example, showing additional filters and fields for advanced search. A similar function is used to expand an inline help panel for [credit card security codes](https://design.visa.com/patterns/card-input/#security-code) using a tooltip button to reveal a content section beneath the input field when selected.

##### Collapsed

The user selects the “Show filters” button to reveal or hide the panel.
<img src="https://design.visa.com/assets/components/accordion/accordion-panel-collapse.svg" alt="A search field and a collapsed button with a plus sign icon that is labelled 'Show filters'"/>
- Use text or context clues to indicate that the panel will expand to reveal additional actions.
- Use the plus (+) icon to indicate collapsed content will expand when selected.

##### Expanded

The user then makes their selection from the available options.
<img src="https://design.visa.com/assets/components/accordion/accordion-panel-expand.svg" alt="A search field and an expanded button with a minus sign icon that is labelled 'Hide filters'. Below it are filter fields 'Filter one', 'Filter two', 'Filter three', with two buttons labelled 'Apply' and 'Reset'."/>
- Allow users to collapse the section by selecting the same action that expanded the section.
- Use the minus (-) to indicate expanded content will collapse when selected.

### Animation
Accordions may animate. Typically, they use a smooth, vertical sliding effect. When a user clicks on an accordion header, the associated content panel expands downward, revealing the hidden content. Conversely, when the header is clicked again, the content panel collapses upward, hiding the content.
<img src="https://design.visa.com/assets/components/accordion/accordion-behaviors-animation.svg" alt="An accordion with a downward animation that gradually reveals content and another animating upward gradually hiding content."/>
- Ensure animations are brief, subtle, and unobtrusive. 
- Implement animations consistently across accordions in your experience, either animating all or none. 

## Platform considerations
### Mobile
#### Full-width accordions

Full-width accordions make it easier for users to select and expand sections on mobile devices and reduce the chance of missed selections. While there's no set limit to the number of accordions on a mobile interface, excessive use can create a cluttered and overwhelming experience.
<img src="https://design.visa.com/assets/components/accordion/accordion-platform-full.svg" alt="An accordion expands to the full width of the screen in a mobile layout."/>
- Use full-width accordions for screen sizes where users would benefit from extra touch space. 
- Consider simplifying the interface or reevaluating the information architecture if many accordions are needed.

## Content
- Use simple language—avoid abbreviations or jargon. 
- Use sentence case, except for proper nouns or acronyms.
- Use accordions to simplify the interface by hiding content, not to fit more onto the screen.

### Accordion titles

- Use short, concise content across headers or section labels. Aim for a range of five to ten words. 
- Only use punctuation when labels are phrased as questions, such as “How do I edit my billing information?”
- Ensure labels accurately describe the content within the section to help users predict what they will find when expanded.
- Use parallel structure for all labels, using either questions, statements, or nouns. Learn more about parallel structure by visiting [Grammar and punctuation](https://design.visa.com/content/grammar).

### Panel content

- Use complete sentences and proper punctuation within each section or panel.
- Keep the content within each panel concise and to the point. 
- Avoid unnecessary details or complex language. 
- Provide users with the answers they need as quickly and efficiently as possible.
- If content within the accordion is becoming too lengthy, it may be a sign that the information should be presented in a different way, such as being broken down further, moved to a separate page, or even represented visually.



---

# accessibility

---
title: Anchor link menu
description: Link menus that navigate to sections within the current page.
meta_description: Find accessibility guidelines for link menus that navigate to sections within the current page.  
thumbnail: assets/components/anchor-link-menu-graphic.svg
tab_order: 2
---

## Best practices

- Ensure all links have unique labels and destinations. 
- Use `aria-current=&quot;true&quot;` on the current link.
- Customize the list elements to fit your site's navigation and hierarchy. Provide an `aria-label` for the landmark to help users navigate to this section and see it listed in a page summary.

## Keyboard controls
Keyboard actions and their corresponding behaviors for anchor link menu

- Key: Navigates to the destination of the link in focus.

- Key: Navigates between links.



---

# index

---
title: Anchor link menu
tab_title: Code
thumbnail: assets/components/anchor-link-menu-graphic.svg
description: Link menus that navigate to sections within the current page.
meta_description: Get code for link menus that navigate to sections within the current page.
categories:
  - navigation
  - structure-and-layout
---

## Component Code Examples: anchor-link-menu

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the anchor-link-menu component
const component = parsed.components.find(c => c.name === 'anchor-link-menu');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `anchor-link-menu`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Anchor link menu
description: Link menus that navigate to sections within the current page.
meta_description: Learn how to use link menus that navigate to sections within the current page.  
keywords: ["Jump menu", "skip navigation menu", "page jump menu", "in-page navigation menu", "table-of-contents links", "link", "links"]
related:
  components:
    - vertical-navigation
    - link
    - navigation-drawer
  content:
    - information-architecture
tab_order: 1
---

The anchor link menu is a set of links mapping to different sections of the same page. It provides a high-level view of the page’s structure and content, and enables users to navigate quickly without having to manually scroll.<br/><br/>
Also known as: Jump menu, skip navigation menu, page jump menu, in-page navigation menu, table-of-contents links.

## Anatomy
<img src="https://design.visa.com/assets/components/anchor-link-menu/anchorlink-anatomy.svg" alt="An anchor link menu with nested levels. "/>

**A. Section title (optional):** Label used to group or organize navigational links.<br/>
**B. Active link indicator (required):** Visual indicator showing the active menu item.<br/>
**C. Navigational link (required):** Label indicating the destination of the menu item on the page.<br/>
**D. Vertical rule (required):** Element separating the anchor link menu from page content.

## Usage

When to use and when not to use anchor link menu

- When to use: To jump to every sub-section on a page.

- When to use: For mobile experiences. Consider using a [Navigation drawer](https://design.visa.com/components/navigation-drawer) instead.

## Best practices
- Ensure the order of the menu items is consistent with the corresponding section headings throughout the application.
- Ensure text within the anchor link menu wraps to a second line instead of truncating to ensure it’s fully visible to users. 
- Clearly indicate the active menu item to help users know which item corresponds to the displayed content section.
- Avoid exceeding two levels of hierarchy within menus.
- Follow [Link](https://design.visa.com/components/link) guidance when implementing anchor link menus.

### Section titles and nesting
Section titles refer to static text used to group navigation items under a common category. This text isn’t interactive and can be used with or without nested navigation items. Nesting refers to organizing navigational items according to their level of hierarchy on the page. Both methods group related content and help users navigate easily.

         
          #### Section titles
          Section titles group navigation items without nesting them. They’re helpful for providing context for the menu on a page.  
          <img src="https://design.visa.com/assets/components/vertnav/accordion-chevron-collapse-1.svg" alt="An anchor link menu with links grouped under the section title of 'Visa Direct.'"/>
          - Use only one section title per menu.      
      
         
          #### Nesting
          Nesting links group related items in a hierarchical order. They’re helpful for more content-heavy applications.          
          <img src="https://design.visa.com/assets/components/vertnav/accordion-chevron-expand-1.svg" alt="An anchor link menu with links grouped under the section title of 'Visa Direct' and two links nested under 'Pricing' labeled 'Individuals' and 'Businesses.'"/>
          - Limit nesting to two level of hierarchy for simplicity.        
      

## Behaviors

### Scrolling behavior
When a user clicks on a navigational link in the menu, the page will scroll to that content section. The active indicator then moves to the corresponding menu item. As the user scrolls down the page, the current location within the menu should be updated. The anchor link menu should always remain visible and in the same position.
<img src="https://design.visa.com/assets/components/anchor-link-menu/anchorlink-behaviors-scroll.svg" alt="An anchor link menu with a section title of 'On this page' at the top and below are level one links and level two links nested"/>

## Content
- Write all content in sentence case, except for acronyms or proper nouns,
- Ensure menu items match section headings to enhance the user’s understanding of the site’s information hierarchy. 
- Don’t use punctuation for links.
- Limit menu labels to a few brief words to prevent unnecessary reflow. 
- Reference [Grammar and punctuation](https://design.visa.com/content/grammar) to learn how to use parallel structure for consistent phrasing.


---

# accessibility

---
title: Avatar
description: Icons and/or text that represent users or entities.
meta_description: Find accessibility guidelines for visual or textual representations of users or entities within products. 
thumbnail: assets/components/avatar-graphic.svg
tab_order: 2
---

## Best practices

- Ensure avatars always have accessible names for screen readers. As mentioned in the [usage guidelines](https://design.visa.com/components/avatar/usage) they must have accessible names such as `aria-label` or `alt` attributes. In the case of initials, the accessible name should be the full name.
- Add `role=&quot;img&quot;` to all avatars that are not placed directly on an `img`.
- Reference examples of avatars used in [Dropdown menu](https://design.visa.com/components/dropdown-menu) and [Horizontal navigation](https://design.visa.com/components/horizontal-navigation) for more.

## Keyboard controls
Keyboard actions and their corresponding behaviors for avatar

- Key: Prompts buttons. If using `role=&quot;button&quot;`, make sure these key commands work.



---

# index

---
title: Avatar
tab_title: Code
thumbnail: assets/components/avatar-graphic.svg
description: Icons and/or text that represent users or entities.
meta_description: Get code for visual or textual representations of  users or entities within products.
---

## Component Code Examples: avatar

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the avatar component
const component = parsed.components.find(c => c.name === 'avatar');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `avatar`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Avatar
description: Icons and/or text that represent users or entities.
meta_description: Learn how to use visual or textual representations of users or entities within products. 
keywords: ["User icon", "user avatar", "profile image", "profile avatar", "thumbnail", "UIImageView (iOS)", "ImageView (Android)"]
related:
  components:
    - vertical-navigation
    - horizontal-navigation
tab_order: 1
---

Avatars are visual and/or textual representation elements of users and entities within a product. They help to personalize products and tailor experiences to the user and their preferences.<br/><br/>
Also known as: User icon, user avatar, profile image, profile avatar, thumbnail, UIImageView (iOS), ImageView (Android).

## Anatomy

<img src="https://design.visa.com/assets/components/avatar/avatar-anatomy.svg" alt="An avatar labelled 'AM' shown with callout A indicating the required Icon, text, initials, or images and callout B indicating the optional dropdown chevron."/>

**A. Avatar element (required):** Icon, text, initials, or image representing the user or profile.<br/>
**B. Dropdown chevron (optional):** UI icon indicating the menu can expand or collapse.

## Usage

When to use and when not to use avatar

- When to use: As a visual representation of a user or entity in your application.
- When not to use: In situations where privacy is a concern, as displaying a user's avatar might not be appropriate.

- When to use: For a more personalized user experience. Can be used to indicate who is currently logged in, which is especially useful in multi-user environments.
- When not to use: If the avatar doesn't serve a clear function like leading to a user's profile or settings.

## Best practices
- Use avatars to identify users in the main part of the app navigation. 
- Implement avatars to function as nav menus when used in navigation components.
- Apply proper alt text to any images such as the user’s name when icons, initials, or images are used.
- Enable users to change the avatar style of their experience.
- Reference [Fictitious brand and user aliases (internal only)](https://bookmarks.visa.com/vpds-fictitious-brands)<!-- aria-label="Fictitious brands and aliases (internal only, opens in new tab)" --> guidelines for placeholder names.
- Follow all guidance for implementing [badges](https://design.visa.com/components/badge/usage) on avatars.

### Avatar styles
There are four styles of avatars that can be used within an experience. Consider selecting a default avatar style for your application and enabling users to customize this style at a later time.

#### Icon

The icon avatar is a generic representation of a user using an icon.
<img src="https://design.visa.com/assets/components/avatar/avatar-bp-icon.svg" alt="Icon variation of an avatar with a dropdown chevron."/>

#### Text

The text avatar displays the user's name in an adjustable text format.  
<img src="https://design.visa.com/assets/components/avatar/avatar-bp-text.svg" alt="Text variation of an avatar labelled 'Alex Miller' with a dropdown chevron."/>

#### Initials

The initials avatar shows the user's initials in one or two characters. 
<img src="https://design.visa.com/assets/components/avatar/avatar-bp-initials.svg" alt="Initial variation of an avatar labelled 'AM' with a dropdown chevron."/>

#### Image

The image avatar uses a customizable profile image to represent the user.
<img src="https://design.visa.com/assets/components/avatar/avatar-bp-image.svg" alt="Image variation of an avatar shown as 'A smiling woman with black hair and glasses' with a dropdown chevron."/>

## Behaviors

### Avatar used in navigation
When an avatar is used in navigation components, it’s treated the same as navigation links that activate a nav menu. In the pressed state, the background color of the avatar will change to match the background color of the nav menu. To learn more, reference [Horizontal navigation](https://design.visa.com/components/horizontal-navigation) guidance.
<img src="https://design.visa.com/assets/components/avatar/avatar-behaviors-nav-menu.svg" alt="Icon avatar shown in the horizontal navigation with a dropdown chevron expanded to display three options 'Profile', 'Security', and 'Preferences'."/>

### Profile representation
Representing a user profile, account, issuer, or brand can use the same basis without the menu button.
<img src="https://design.visa.com/assets/components/avatar/avatar-bp-profile.svg" alt="Three avatars shown without the menu button, emphasizes size based on factors of four and consistency."/>
- Use standard icon sizes of 24x24 or 48x48. Whichever size you choose, be consistent throughout the application.

## Content
- Always use title case for names including companies or entities.
- Don’t use punctuation. 
- Follow all best practices and guidelines implementing links. Reference [Link](https://design.visa.com/components/link) for more information.  
- Reference [Grammar and punctuation](https://design.visa.com/content/grammar) to learn how to use parallel structure for consistent phrasing in navigation.


---

# accessibility

---
title: Badge
description: Visual indicators that communicate the status of a component. 
meta_description: Find accessibility guidelines for visual indicators that communicate the status of a component. 
thumbnail: assets/components/badge-graphic.svg
tab_order: 2
---

## Best practices

### Label badges

- Avoid using label badges alone to convey information.
- Always place icon badges near their associated labels to convey information through visible text.
- Avoid labeling icons individually or giving them screen reader focus, as this creates redundancy. Screen reader focus should wrap the icon and the label, reading the label information, e.g., "! Out of stock".

### Icon badges

- Use an `aria-label` to communicate an accessible name.



---

# index

---
title: Badge
tab_title: Code
thumbnail: assets/components/badge-graphic.svg
description: Visual indicators that communicate the status of a component. 
meta_description: Get code for visual indicators that communicate the status of a component. 
categories:
  - feedback-and-status
---

## Component Code Examples: badge

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the badge component
const component = parsed.components.find(c => c.name === 'badge');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `badge`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Badge
tab_title: Usage
description: Visual indicators that communicate the status of a component.
meta_description: Learn how to use visual indicators that communicate the status of a component.
tab_order: 1
keywords: ["Info tag"]
related:
  patterns:
    - feedback-and-status
---

Badges provide brief information, statuses, or counts related to an item or element. They can be used to draw attention to new or important information, such as notifications, messages, or updates.<br/><br/>
Also known as: Info tag.

## Anatomy

<img src="https://design.visa.com/assets/components/badge/badge-anatomy.svg" alt="Anatomy of a badge"/>

**A. Icon (optional):** Leading icon used to represent badges that can be used with or without a label.<br/>
**B. Label (optional):** Brief text providing information about a specific item or element.<br/>
**C. Background color (required):** Visual indicator to help convey the badge status.

## Usage

When to use and when not to use different types of badges

- Component: If text is needed to describe the status.
- When to use: If the text is too long or complex.

- Component: To indicate counts of the element it’s tied to, like notifications.
- When to use: If the count doesn’t provide meaningful information to the user.

## Best practices

- Ensure badges are static and not interactive.
- Ensure badges are easily noticeable but don’t obscure their associated element or other important information.
- Avoid using badges if they add complexity, ambiguity, or visual noise. 
- Ensure the label text, icons, and background color collectively convey the badge information accurately.

### Label badges
Label badges use text to convey information. Ensure the label and background color match to accurately convey the badge information. For example, only use the yellow background color to convey warning information.

<img src="https://design.visa.com/assets/components/badge/badge-bp-label-only.svg" alt="Different badges with different backgrounds and labeled according to the type of information each badge is conveying."/>

<div>
    
                    
              #### Label and icon badge

              Use icons to indicate status or condition of an element, especially for common meanings.  

              <img src="https://design.visa.com/assets/components/badge/badge-bp-icon-label.svg" alt="Icon and label badge combination example"/>     
          
       
                    
              #### Label badge with ellipse

              Use the ellipse indicator when more visual emphasis is needed and intuitive icons aren’t available.   

              <img src="https://design.visa.com/assets/components/badge/badge-bp-elipse-label.svg" alt="Ellipse and label badge combination example"/>     
          
    
</div>

### Number badges

Number badges are small, circular badges that only convey a count or number. They're commonly used to indicate notifications. They can be paired with UI icons such as the notification bell or with other components such as [tab bars](https://design.visa.com/components/tab-bar). They’re tied to the element that it represents the count for.

<img src="https://design.visa.com/assets/components/badge/badge-bp-number.svg" alt="Example of a number badge for notifications"/>

### Placement

Badges are typically placed alongside the element they are supporting or calling attention to.

<img src="https://design.visa.com/assets/components/badge/badge-bp-placement.svg" alt="Red badge used to call attention to the overdue status of an account"/>

#### Section notifications

Section notifications group related messages to help organize large numbers of notifications. A number badge can be attached to different sections to show unread items. When a user navigates to a section, the notifications appear, and the badge disappears. Not all sections may need notifications, so consider whether a global notification system might work better for your application.

<img src="https://design.visa.com/assets/components/badge/badge-bp-section-notifications.svg" alt="Badge used for section notifications in vertical navigation"/>

## Platform considerations

### Mobile
In mobile designs, badges can appear as an individual ellipse when the number badge is too large compared to the component or icon. In this scenario, the badge indicates that one or more notifications are available, but doesn't indicate how many or provide specific status updates.

<img src="https://design.visa.com/assets/components/badge/badge-platform-mobile.svg" alt="Example of a mobile use case for a badge"/>

## Content

- Use simple language—avoid abbreviations or jargon.
- Write all content in sentence case, except for acronyms or proper nouns.
- Don’t use punctuation for badge labels.
- Limit labels to a few short words. 
- Reference [Grammar and punctuation](https://design.visa.com/content/grammar) to learn how to use parallel structure for consistent phrasing.


---

# accessibility

---
title: Banner
description: Messages that indicate the global status of an application or website.
meta_description: Find accessibility guidelines for messages that indicate the global status of an application or website. 
thumbnail: assets/components/banner-graphic.svg
tab_order: 2
---

## Best practices

- Don’t move focus to the banner when it opens to avoid interrupting the user’s work flow.
- Position the banner at or near the top of the page content in the DOM.
- Ensure banners remain visible even when the page is scrolled below the fold.
- Ensure banners never cover the rest of the page, even with high zoom levels and small screen sizes.
- Use  roles and attributes to announce the banner content to the user.

### Screen reader

`role=&quot;alert&quot;` is used to communicate an important and usually time-sensitive message to the user.
- Use `role=&quot;alert&quot;` for error messages and system messages. This is equivalent to `aria-live=&quot;assertive&quot;` paired with `aria-atomic=&quot;true&quot;`.<br/>

`role=&quot;status&quot;` is used to communicate  information that isn’t important enough to be an alert.
- Use `role=&quot;status&quot;` for informational or success messages. This is equivalent to `aria-live=&quot;polite&quot;` paired with `aria-atomic=&quot;true&quot;`.

## Keyboard controls
Banners are comprised of other elements that use standard keyboard actions.<br/><br/>
**Note:** Activating the Escape key does not close the banner, as that might disrupt what the user is doing by closing something else.

  Keyboard actions and their corresponding behaviors for banner

- Key: Moves focus to the next focusable element.

- Key: Prompts the action associated with the focused interactive element.

- Key: Moves keyboard focus backwards to the previous interactive element in the banner.



---

# index

---
title: Banner
tab_title: Code
thumbnail: assets/components/banner-graphic.svg
description: Messages that indicate the global status of an application or website.
meta_description: Get code for messages that indicate the global status of an application or website. 
categories:
  - feedback-and-status
---

## Component Code Examples: banner

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the banner component
const component = parsed.components.find(c => c.name === 'banner');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `banner`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Banner
tab_title: Usage
tab_order: 1
description: Messages that indicate the global status of an application or website.
meta_description: Learn how to use messages that indicate the global status of an application or website. 
keywords: ["Status alert", "global status message", "informational notice", "site notice"]
related:
  components:
    - section-message
    - flag
  patterns:
    - feedback-and-status
  content:
    - messaging
---

Banners provide global or system-level messages on the status of an application or site. They provide updates from low to critical priority and often include a follow-up action for the user. 
<br />
Also known as: Status alert, global status message, informational notice, site notice.

## Anatomy

<img src="https://design.visa.com/assets/components/banner/banner-anatomy.svg" alt="Warning banner with callout A indicating the required icon, callout B indicating the optional title, callout C indicating the required message, callout D indicating the optional close icon button, and callout E indicating the optional button and link."/>

**A. Icon (required):** Visual indicator communicating the urgency of the banner. <br/> **B. Title (optional):** Brief text summarizing the purpose of the banner. <br/> **C. Message (required):** Descriptive message detailing important contextual information. <br/> **D. Close icon button (optional):** Optional action allowing users to dismiss a banner without completing a call to action. <br/> **E. Button and link (optional):** Text button or link that prompts an action or directs users to relevant resources.

## Usage

When to use different types of banners

- Component: For system-level feedback or status messages that require the user’s attention without disrupting their workflow or requiring immediate action.
- When to use: For informational messages that are of high enough priority to disrupt the user's workflow, even though they may not require immediate action. Use a [Dialog](https://design.visa.com/components/dialog/usage) instead. <br/><br/> For low-priority status updates contextually relevant to the user’s current workflow. Use a [Section message](https://design.visa.com/components/section-message/usage) instead. <br/><br/> For low-priority messages that don't require user action or attention. Use a [Flag](https://design.visa.com/components/flag/usage) instead.

- Component: Success banners are not a common use case as they require more attention than needed for low-priority messages.
- When to use: For system- or section-level success, messages including on-page event confirmations. Use a [Flag](https://design.visa.com/components/flag/usage) instead. <br/><br/> If the user is taken to a success page on submit. Don’t a messaging component in this case.

- Component: For medium-priority warning messages that require the user's attention and may or may not require action immediately or in the near future.
- When to use: For medium-priority messages that are of high enough priority to disrupt the user's workflow. Use a [Dialog](https://design.visa.com/components/dialog/usage) instead. <br/><br/> For warnings contextually relevant to a section of a page or workflow. Use a [Section message](https://design.visa.com/components/section-message/usage) instead. <br/><br/> For low-priority warnings that don’t require user action or attention. Use a [Flag](https://design.visa.com/components/flag/usage) instead.

- Component: For high-priority, system-level messages alerting that errors or issues have occurred that require immediate action or attention.
- When to use: For high-priority alerts communicating that critical errors  have occurred and must be fixed before continuing. Use a [Dialog](https://design.visa.com/components/dialog/usage) instead. <br/><br/> For high-priority errors contextually relevant to a section of a page or workflow. Use a [Section message](https://design.visa.com/components/section-message/usage) instead.

## Best practices

  - Visit [Button](https://design.visa.com/components/button/usage) to learn about best practices for alignment, order, and language for calls to action.<br/>
  - Visit [Feedback and status](https://design.visa.com/patterns/feedback-and-status) to learn how to use messaging components, understand their level of disruption, and choose the appropriate messaging component for your context.

## Behaviors

### Dismissal

In general, users should be allowed to dismiss banners using a close icon button or text button. Banners should also dismiss when users complete an associated action, such as correcting an error. Avoid using timed auto-dismissal for banners, as they may disappear before screen readers finish announcing the text.

### Display methods

There are two primary methods for displaying banners: Scrolling with page content (recommended) or floating over page content. Floating banners are more disruptive and should only be used for high-priority messages.

<div>
    
          
              #### Scrolls with page (recommended)
             
               Banners that scroll with page content are fixed below the navigation bar and remain there as users scroll. This is the least disruptive way to implement banners. 
                      
              <img src="https://design.visa.com/assets/components/banner/banner-behaviors-display-scroll.svg" alt="Banner scrolls with page content"/>
      
               - Place these banners within page content below the navigation bar. <br/>
               - Use these banners for low and medium-priority messages without disrupting the flow of content.  
          

          
              #### Floats above page content
           
               Floating banners float over page content. They remain in view when users scroll but may obstruct important interactive controls.  

              <img src="https://design.visa.com/assets/components/banner/banner-behaviors-display-float.svg" alt="Banner floating above page content"/>
             
               - Reserve floating banners for high-priority messages that require immediate attention. <br/>
               - Always float banners on mobile screens for accessibility reasons. Visit [Platform considerations](https://design.visa.com/components/banner/usage/#platform-considerations) for more info.           
          
    
</div>

### Animation

Banners may use animated graphics. When animated, banners appear by sliding downwards from the top of the page and reverse when dismissed. 

<img src="https://design.visa.com/assets/components/banner/banner-behaviors-animation.svg" alt="Banner animates downward on appearance"/>

- Ensure animations are brief, subtle, and unobtrusive. <br/>
- Use animations consistently for all banners in your experience.   

## Content

- Learn how to craft content for messaging components, like banners, visit [Messaging](https://design.visa.com/content/messaging). <br/>
- Follow guidelines for [Link](https://design.visa.com/components/link/usage) and [Button](https://design.visa.com/components/button/usage) components when labeling actions and destinations within banners. 

## Platform considerations

### Mobile
Banners are available in both web and mobile and should be implemented similarly across platforms.<br/>
- Always float banners on mobile screens. This ensures they remain visible if users zoom or navigate non-linearly.  



---

# accessibility

---
title: Breadcrumbs
description: Supplemental navigation that indicates the user’s location in a site or app.
meta_description: Find accessibility guidelines for supplemental navigation that indicates a user’s location in a site or app.
thumbnail: assets/components/breadcrumbs-graphic.svg
tab_order: 2
---

## Best practices

- Contain all breadcrumb links in an ordered list ( `ol`) as list items, because their ordering indicates positioning in the breadcrumb.
- Ensure the containing element for the breadcrumbs is a `nav` element and give it an `aria-label` to differentiate it from other navigation regions.
- Use `aria-current=&quot;page&quot;` to identify the current breadcrumb page.  It is implemented as a span.
- Check that the separator icons use the library’s right-to-left class if needed.

## Keyboard controls

  Keyboard actions and their corresponding behaviors for breadcrumbs

- Key: Activates the focused breadcrumb link to navigate to the corresponding page.

- Key: Moves focus to the breadcrumb links sequentially.

- Key: Move focus backward through the breadcrumb links.



---

# index

---
title: Breadcrumbs
tab_title: Code
thumbnail: assets/components/breadcrumbs-graphic.svg
description: Supplemental navigation that indicates the user’s location in a site or app.
meta_description: Get code for supplemental navigation that indicates a user’s location in a site or app.
---

## Component Code Examples: breadcrumbs

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the breadcrumbs component
const component = parsed.components.find(c => c.name === 'breadcrumbs');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `breadcrumbs`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Breadcrumbs
description: Supplemental navigation that indicates the user's location in a site or app.
meta_description: Learn how to use supplemental navigation that indicates a user's location in a site or app.
keywords: ["Breadcrumb trail", "cookie crumb trail"]
related:
  components:
    - link
tab_order: 1
---

Breadcrumbs are a supplemental navigation element that help users with wayfinding. They indicate the user's current location within a website or app and streamline navigation across multiple layers of pages, folders, or files.
<br />
Also known as: Breadcrumb trail, cookie crumb trail.

## Anatomy

<div className="resize_mobile" style={{marginBlockEnd: "16px"}}>
  <img src="https://design.visa.com/assets/components/breadcrumbs/breadcrumbs-anatomy.svg" alt="Breadcrumb link section with letters pointing to different parts. A is pointing to a Level 1 link. B is pointing to a / character between each link. C is pointing to the last Level in the list, which is not a link."/>
</div>
**A. Link (required):** Standalone link component with an underline. <br/> **B. Separator (required):** Character appearing between each link, either a forward slash: (‘/’) or svg: (‘>’). <br/> **C. Current page (required):** Non-interactive text representing the user’s current location.

## Usage

When to use and when not to use breadcrumbs

- When to use: To help users understand their current location within the information hierarchy of an app or site.
- When not to use: For linear web pages without multiple levels of page hierarchy.

- When to use: As a secondary form of navigation.
- When not to use: In place of a site’s main navigation.

## Best practices

  - Use breadcrumbs consistently across your site. If you use them on one page, use them on all pages where they're relevant.<br/>
  - Always include the user's current page as the last item. The current page isn’t a link and should appear different from the other breadcrumb items, which are active links.

### Breadcrumb trails

There are generally three strategies for generating breadcrumb trails: location-based, path-based, and attribute-based breadcrumbs. These include location-based, path-based, and attribute-based breadcrumbs.
<br />
Following [design recommendations](https://www.nngroup.com/articles/breadcrumbs/)<!-- aria-label="design recommentdations (opens in a new tab)" --> from the Nielsen Norman Group, we suggest primarily using the location-based strategy. However, there may be exceptions where path- and attribute-based breadcrumbs fit your use case.

#### Location-based breadcrumb trails (recommended)

Location-based breadcrumbs show the user’s location within a site’s hierarchy. They are the suggested form of breadcrumbs because they provide a clear route that is not repetitive or lengthy, which can happen with other types of breadcrumbs.

<div className="resize_mobile">
  <img src="https://design.visa.com/assets/components/breadcrumbs/breadcrumbs-breadcrumbtrails-location-based.svg" alt="Breadcrumbs that say Home / Blog posts / March 2022 / Blog post 2"/>
</div>
- Always start with the home page or base level of hierarchy. This provides a clear starting point and helps users understand the overall hierarchical structure.

#### Path-based breadcrumbs (alternative strategy)

Path-based trails show the pages a user visited to get to their current page. This strategy shows the specific path a user took but might not reflect site hierarchy.
<div className="resize_mobile">
  <img src="https://design.visa.com/assets/components/breadcrumbs/breadcrumbs-breadcrumbtrails-path-based.svg" alt="Breadcrumbs that say Design / Design Kits / VAULT / PDF"/>
</div>
  - Include every page a user has visited to ensure the path is accurate and consistent.

#### Attribute-based breadcrumbs (alternative strategy)

Attribute-based trails show the attributes or characteristics of the items on a page. This works best when page contents can be categorized in multiple ways, not just within a single hierarchical structure, such as an e-commerce site.
<div className="resize_mobile">
 <img src="https://design.visa.com/assets/components/breadcrumbs/breadcrumbs-breadcrumbtrails-attribute-based.svg" alt="Breadcrumbs that say Job opportunities / City: New York / Role: UX design"/>
</div>
  - Identify both the attribute type and specific attribute in the breadcrumb trail.

## Content

  - Write all content in sentence case, except for acronyms or proper nouns.<br/>
  - Don’t use punctuation, except for colons in attribute-based trails.<br/>
  - Ensure labels match page titles to enhance the user’s understanding of the site’s information hierarchy.<br/>
  - Follow all best practices and guidelines implementing links. Reference [Link](https://design.visa.com/components/link/usage) for more information.

## Platform considerations

 ### Mobile

Breadcrumbs are not common in native mobile apps. Instead, consider using a back-facing arrow UI button to let users navigate back one level in site hierarchy. 

<img src="https://design.visa.com/assets/components/breadcrumbs/breadcrumbs-platform-mobile.svg" alt="Page title text is in the middle of the screen. To the left of the text is an arrow pointing left."/>
- Reference [Link](https://design.visa.com/components/link/usage) for more information on “Back to” links.

### Web

Breadcrumbs are commonly used on websites with many pages that are organized hierarchically.

<img src="https://design.visa.com/assets/components/breadcrumbs/breadcrumbs-platform-web.svg" alt="Web example showing the breadcrumbs are underneath the banner and above the h1"/>

  - Place breadcrumbs at the top of a page between the navigation bar and page title.<br/>
  - Don’t use breadcrumbs on sites where every page is accessible from a global navigation bar.

---

# accessibility

---
title: Button
tab_order: 2
description: Interactive elements that help users take actions within an interface.
meta_description: Find accessibility guidelines for interactive elements that help users take actions within an interface.
thumbnail: assets/components/button-graphic.svg
---

## Best practices

- Ensure icon-only buttons have an `aria-label` for screen readers.
- Don’t put block level elements such as divs inside buttons. Only use spans, images, svgs, and text inside buttons.
- Ensure all buttons meet touch target requirements, especially on mobile devices.
- Use attributes `type=&quot;submit&quot;` or `type=&quot;reset&quot;` when appropriate for buttons used inside forms.

## Keyboard controls

  Keyboard actions and their corresponding behaviors for buttons

- Key: Prompts the action associated with the &lt;button&gt;. If you’re using `role=&quot;button&quot;`, make sure these key commands work.



---

# index

---
title: Button
tab_title: Code
description: Interactive elements that help users take actions within an interface.
meta_description: Get code for interactive elements that help users take actions within an interface.
thumbnail: assets/components/button-graphic.svg
categories:
  - actions
---

## Component Code Examples: button

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the button component
const component = parsed.components.find(c => c.name === 'button');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `button`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples


---

# usage

---
title: Button
tab_title: Usage
tab_order: 1
description: Interactive elements that help users take actions within an interface.
meta_description: Learn how to use interactive elements that help users take actions within an interface. 
keywords: ["Push button", "actions drop-down", "action menu", "UI button (Native iOS)", "button (Android)", "elevated button (Flutter)"]
related: 
  components: 
    - link
  patterns:
    - forms
---

{/* INTRO */}
Buttons are selectable elements that allow users to take action. They typically communicate a call to action (CTA) using text, icons, or both. Buttons are utilized across a range of interfaces including dialogs, forms, and content cards.<br/><br/>

Also known as: Push button, actions drop-down, action menu, UI button (Native iOS), button (Android), elevated button (Flutter).

{/* ANATOMY */}

  ## Anatomy

  <img src="https://design.visa.com/assets/components/button/button-anatomy.svg" alt="Two primary buttons labeled &lt;primary action,&gt; one with a leading icon and the other with a trailing icon. The first button has two callouts: A. pointing to the leading icon and B. pointing to the required label. The second button has callout: C. pointing to the trailing icon."/> 

  **A. Leading icon (optional):** Icon located before the button text used to enhance the meaning of the text.<br />
  **B. Label (required):** Text communicating what action will be performed when the user interacts with it.<br />
  **C. Trailing icon (optional):** Icon located after the button text used to enhance the meaning of the text.
 

{/* USAGE */}

  ## Usage

  When to use different types of buttons

- Component: To emphasize the most important or common call to action.
- When to use: For actions of equal importance to others or another primary button.

- Component: For calls to action that are less important or the opposite of the primary.
- When to use: For the principle or most important action or without a primary button.

- Component: For the least important call to action. <br /><br />
          For sub actions when the primary and secondary are present.
- When to use: For actions of high use or importance. <br /><br />For destructive actions that might be accidentally selected. <br />

- Component: To emphasize that an action could have a destructive or irreversible effect, such as deleting data.
- When to use: For non-destructive actions.

- Component: For displaying actions in a compact area.<br /><br />To implement buttons with more visual appeal.
- When to use: When the meaning of an icon is unclear.<br /><br />When icon buttons aren’t consistently used within the UI.

- Component: Within components and when the action is universally recognized.
- When to use: When the meaning of an icon is unclear.

{/* BEST PRACTICES */}

## Best practices
  - Only use buttons for actions, not navigational elements. Use a [Link](https://design.visa.com/components/link) to take users to a new destination.
  - Use consistent design, placement, and behavior for buttons throughout interfaces. This helps users predict interactions.
  - Avoid using more than five text buttons per interface. Consider using a [Dropdown menu](https://design.visa.com/components/dropdown-menu) to group more than five actions.
  - Group buttons into logically based on the relationship or tasks users are trying to accomplish with your interface.

{/* DO + DON'T */}

{/* PRIMARY BUTTONS */}

### Primary buttons
 
  Primary buttons are high emphasis and use fill to draw attention. They can be used independently or in groups where one call to action needs to stand out more than others.
  - Use them sparingly to draw attention to the most important action on a screen.
  - Place primary buttons in expected locations, ensuing they are easy to find and follow the natural flow of the page.

{/* DO + DON'T */}

{/* SECONDARY BUTTONS */}

  ### Secondary buttons
 
  Secondary buttons are medium emphasis and use an outline with no fill. They’re commonly paired with primary buttons to perform the opposite or negative action compared to primary buttons, for example “Next” and “Back”, or “Submit” and “Cancel”. However, they can also be used independently or in groups. 
  - Use secondary buttons for common actions when high emphasis isn't needed.
  

{/* - DO + DON'T */}

  

{/* TERTIARY BUTTONS */}

### Tertiary buttons
    
    Tertiary buttons are the least prominent compared to primary and secondary buttons. They can be used independently or in groups with primary and secondary buttons for less important actions.
    - Use tertiary buttons for less important, less frequently used actions. Overuse can dilute their meaning and confuse users.
    - Ensure tertiary buttons are easy to locate and not so subtle that they’re easy to overlook or hard to interact with.
  

{/*  DO + DON'T */}

{/*  DESTRUCTIVE BUTTONS */}

### Destructive buttons

 Destructive buttons should be used sparingly. They have three styles: primary, secondary, and tertiary.
  - Alert users with a warning dialog before a destructive action happens, especially if resulting in data loss.
  - Prevent data loss by placing destructive buttons where they're less likely to be selected by mistake.
  - Allow users to undo destructive actions when possible to give users more control over their actions.

{/*  DO + DON'T */}

{/*  ICON BUTTONS */}

### Icon buttons

Icon buttons are circular, enclosed icons that represent an action. They include an optional label and are available in a medium and large size. Unlike text buttons, icon buttons offer visual appeal and stack vertically in limited horizontal space.
  - Use icon buttons thoughtfully, don’t add visual appeal for the sake of visual appeal.
  - Size icons consistently and use or exclude icon button labels across experiences.

{/* - DO + DON'T */}

{/*  UI ICON BUTTONS */}

### UI icon buttons

 
  UI icons buttons are visual representations of an action that don’t require labels. They exist within other components or on their own.
    - Ensure icons clearly and intuitively indicate the action they represent. 
    - Make sure UI icons are large enough to be usable, especially on touch devices.

{/* - DO + DON'T */}

  
{/* Order */}

### Order

Order refers to the sequence of buttons and which action comes first in a group. Buttons should be ordered logically based on user expectations. This frequently aligns with reading order, meaning primary buttons appear on the left for left-to-right languages. However, common exceptions exist. For example, navigational buttons in a form or wizard where “Next” would be placed in the right position to indicate forward progress.
  - Be consistent across your interface. If the primary action is usually on the left, avoid switching it for specific instances.
  - Group related actions, for example, "Cut", "Copy", and "Paste" are often grouped together in text editing interfaces.

{/* DO + DON'T */}

{/* Alignment */}

### Alignment
 
 
  Alignment refers to the position of buttons or button groups along a common edge within a container. In left-to-right languages, users typically scan content left-to-right, then top-to-bottom. Buttons should follow this pattern and align with the content within the container to match these expectations. 
  <br /><br />Buttons within components are typically left-aligned except in wizards, touring tips, or components with full-width buttons.<br /><br />

  
                
      <img src="https://design.visa.com/assets/components/button/button-alignment-dialog.svg" alt="A dialog with two buttons left aligned below the dialog text"/>
      - Left-align buttons by default for left-to-right languages so it’s easier for users to scan content along a common edge.         
    
            
      <img src="https://design.visa.com/assets/components/button/button-alignment-right.svg" alt="A dialog used for touring tips with previous and next buttons in the bottom right corner"/>
      - Right-align navigational buttons to reinforce that there will be forward progress.         
    
  

{/* Size */}

### Size

Text and icon buttons are available in medium and large sizes. UI icon buttons are available in small, medium, and large sizes.

         
          #### Medium buttons

            Medium buttons are the default button size for most use cases, such as forms and dialogs.
            <img src="https://design.visa.com/assets/components/button/button-size-med.svg" alt="A medium primary button and a medium icon button"/>
            - Use medium buttons to allow space for interfaces with multiple interactive elements. 
      
         
          #### Large buttons
          
            Large buttons are more expressive and may balance large headings commonly found across landing or web pages. 
          <img src="https://design.visa.com/assets/components/button/button-size-large.svg" alt="A large primary button and a large icon button"/>
          - Use large buttons when space is available and there are few other interactive elements present. 
            
      

{/* BEHAVIORS */}
##  Behaviors

### Styling and coding buttons and links

In general, buttons should be used for in-page actions and links should be used as navigational tools, like leaving a page. Whenever possible, match the visual styling of these elements with their coded and user-expected behavior. However, buttons and links may be styled like one another in some cases. Learn about these exceptions below. 

         
          #### Button coded as links
          Buttons may be coded as links but styled as buttons when necessary. For example, an icon button may be appropriate when linking to a shopping cart. 
          <img src="https://design.visa.com/assets/components/button/button-behavior-linkbutton.svg" alt="A button labeled checkout with an arrow icon, a button labeled visit cart with an arrow icon, and a shopping cart icon."/>
          - Use the arrow icon whenever possible as a visual cue that selecting will navigate to another page.      
      
         
          #### Link coded as buttons
          Links may be coded as buttons but styled as links when necessary. For example, buttons may be styled as links when information will be presented in an overlay or dialog.          
          <img src="https://design.visa.com/assets/components/button/button-behavior-buttonlink.svg" alt="A link with icon labeled add, edit, and learn more."/>
          - Avoid underlining links coded as buttons, as this style is reserved for links, not buttons.         
      

{/* CONTENT */}

## Content

  - Always use sentence case except for proper nouns or acronyms.
  - Use clear, actionable, language that is easy to understand without additional context or information.
  - Avoid abelist verbs that focus on senses. For example, use “Play video,” instead of “Watch video” or “Explore results” instead of “See results”.

  ### Button formulas
  - Combine action or command verbs with nouns to make buttons specific.
    - \{verb\} + \{noun\} is useful for most product cases.
    - \{verb\} + \{adverb\} is typically used for marketing and promotions.
  - Only use single word labels for common navigational actions such as, “Next,” “Continue,” “Back,” “Close,” “Cancel,” “OK,” “Accept,” “Done,” or “Finish.”

{/* DO + DON'T x 4 */}

{/* PLATFORM CONSIDERATIONS */}

## Platform considerations
 
### Mobile

#### Full-width buttons

Full-width buttons make it easier for users to select options on mobile devices and reduce the chance of missed selections.

<img src="https://design.visa.com/assets/components/button/button-platform-full.svg"  alt="Dialog example with a primary  and secondary button that fill the width of the dialog box."/>

  - Use full-width buttons within containers when users would benefit from extra touch space. 
  - Avoid using more than two full-width buttons per container to help prevent accidental selections.

#### Stacked buttons

Stacked buttons adds visual balance and provide a larger touch area on small screens.

  <img src="https://design.visa.com/assets/components/button/button-platform-stacked.svg"  alt="Dialog example with a primary  and secondary button that fill the width of the dialog box."/>

  - Arrange buttons in a vertical stack at the bottom of the screen to use the available space more effectively.
  - Avoid stacking too many buttons to prevent overwhelming the user. Limit the options to the most important actions.
  - Help users prioritize actions by placing the most important or expected button at the top.

#### Icon buttons as navigation

Icon buttons can be used in mobile interfaces to provide compact navigation. 

  <img src="https://design.visa.com/assets/components/button/button-platform-iconnav.svg" alt="Dialog example with a primary and secondary button that fill the width of the dialog box."/>

  - Only use icons as navigation when the icon is commonly understood. 
  - Use text in addition to the icon if an icon can be interpreted in multiple ways.
  - Maintain consistent styles for icons. This includes the design as well as placement and behavior.


---

# accessibility

---
title: Checkbox
description: Interactive element that lets users select one or more independent choices.
meta_description: Find accessibility guidelines for interactive elements that let users select one or more independent choices.
thumbnail: assets/components/checkbox-graphic.svg
tab_order: 2
---

## Best practices

- Don’t use the aria-checked attribute for indeterminate checkboxes. Instead, set its indeterminate property to true or false using JavaScript. Reference [the coded examples.](https://design.visa.com/components/checkbox)<!-- aria-label="checkbox code examples" -->
- `fieldset` and `legend` indicate a set of checkbox elements grouped together.
  - Always use the `legend` element to indicate a set of checkbox elements are grouped together. It can be visually hidden if necessary using the library’s screen reader class.
  -  Use an HTML list for the checkboxes to ensure screen readers will announce how many checkboxes are in the group.
-  Ensure additional instructions or error messaging are associated with the checkbox group so screen readers will read them. Reference Angular or React for examples.
- Always use the `required` attribute for legal acknowledgments.
- Ensure each checkbox input has an `id` associating it with its label. Be sure to associate additional text and error messages to its relevant checkbox input or fieldset. Reference the code for more.
- Ensure all checkboxes used in tables have accessible names for screen readers that communicate which row or column they’re associated with. For example, “Select ProjectA”.

## Keyboard controls

Keyboard actions and their corresponding behaviors for checkboxes

- Key: Moves keyboard focus to the next checkbox in a group or next interactive element.

- Key: Selects/unselects the checkbox when the component is in focus.<br/><br/> When the parent checkbox shows the unselected state, all nested checkboxes are unselected. <br/><br/>
When the parent checkbox shows the indeterminate state, selecting the parent checkbox selects all nested options. <br/><br/>
When the parent checkbox shows the selected state, all nested checkboxes are selected.



---

# index

---
title: Checkbox
tab_title: Code
description: Interactive element that lets users select one or more independent choices.
meta_description: Get code for interactive elements that let users select one or more independent choices. 
thumbnail: assets/components/checkbox-graphic.svg
categories:
  - selection-controls
---

## Component Code Examples: checkbox

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the checkbox component
const component = parsed.components.find(c => c.name === 'checkbox');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `checkbox`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Checkbox
description: Interactive element that lets users select one or more independent choices.
meta_description: Learn how to use interactive elements that let users select one or more independent choices. 
keywords: ["Check box", "tick box", "checkBox (Android)"]
related: 
  components: 
    - dropdown-menu
    - radio
    - multiselect
  patterns:
    - forms
tab_order: 1
---

Checkboxes enable users to select one or more options from a short list. They are commonly used in forms, filter menus, or any scenario where users may want to select multiple options from a short list.<br/><br/>

Also known as: Check box, tick box, checkBox (Android).

## Anatomy
<img src="https://design.visa.com/assets/components/checkbox/checkbox-anatomy.svg" alt="A single checkbox with a description below and a checkbox group."/>
**A. Checkbox (required):** Interactive element enabling users to select an option.<br/>
**B. Option label (required):** Brief text describing the checkbox option.<br/>
**C. Description (optional):** Brief message detailing important information about the option. <br/>
**D. Checkbox group (optional):** Two or more related checkboxes presented in a group. <br/>
**E. Group label (required):** Brief description of options available for selection. <br/>

## Usage
When to use and when not to use different types of checkboxes

- Component: To present a binary choice where the user can select or deselect a single option.
- When to use: To present multiple options the user can choose between. Use a checkbox group instead.

- Component: To present a short list of options where the user can select one or multiple.
- When to use: If users must select one option from a short list. Use a [Radio button group](https://design.visa.com/components/radio) instead. <br/><br/> For long lists where all options can't be viewed at once or require scrolling. Use a [Multi-select listbox](https://design.visa.com/components/listbox) instead. <br/><br/> For long lists where users would benefit from entering text to filter or search the list options. Use [Multiselect](https://design.visa.com/components/multiselect) instead. <br/><br/> To present a list of actions. Use a [Dropdown menu](https://design.visa.com/components/dropdown-menu) instead.

- Component: To present a binary choice where the user can select or deselect a single option. <br/><br/> To provide an increased touch area.
- When to use: To present multiple checkbox panels in a list. Use a checkbox panel group instead. <br/><br/> When space is limited.

- Component: To present a short list options where the user can select one or multiple. <br/><br/> To provide an increased touch area.
- When to use: If users can only select one option from a list. Use a [Radio panel group](https://design.visa.com/components/radio) instead. <br/><br/> When space in limited.

## Best practices
- Ensure checkboxes appear visually different when selected and unselected by using the fill color and “check” icon.
- Ensure users can select anywhere within the checkbox or associated option label to choose an option.
- List options in a logical order, either alphabetically or according to the most common or likely selection.
- Avoid using a horizontal layout for checkbox groups and panel groups, as vertical layouts are easier to scan and more adaptable for small screens. 
- Always indicate that more than one option can be selected using phrasing like “Select one or more options”.

### Standalone checkboxes
Standalone checkboxes refer to checkboxes used alone to present a single, independent option that doesn’t relate to any others. They’re typically used to enable settings, agree to terms and conditions, or present a binary choice, where selecting the checkbox indicates agreement and not selecting indicates disagreement. 
- Use the default checkbox component to present a standalone option. 
- Frame options so that selecting the checkbox indicates agreement and not selecting the checkbox indicates disagreement.

### Checkbox panels
Checkbox panels are an alternative to default checkboxes. They’re available as standalone elements or in groups and can be used to draw attention to the checkbox or provide an increased touch area on small screens. 
- Ensure users can select anywhere within the checkbox, label, or panel to choose an option. 

### Checkbox groups
Checkbox groups and panel groups are sets of default checkboxes or checkbox panels placed under a single group label. They’re commonly used to present a short list of related options available for selection.
- Use a checkbox group or panel group for short lists where all options can be viewed without scrolling. 

### Label size for panel groups
Group labels for panel groups are available in two sizes. Use whichever is appropriate depending on your use case and the overall hierarchy of your experience. 

#### Default

The default option is the UI label font size and matches the text in option descriptions.
<img src="https://design.visa.com/assets/components/checkbox/checkbox-size-default.svg" alt="A checkbox panel group with the label size in default."/>
- Use the default size to reduce visual weight for users when multiple checkbox panel groups are used together.

#### Large

The large UI label size is an alternative option that can be used to draw attention to the checkbox panel group label. 
<img src="https://design.visa.com/assets/components/checkbox/checkbox-size-large.svg" alt="A checkbox panel group with the label size in large."/>
- Use the large size to draw attention to a standalone checkbox panel group.

### Hidden labels
Checkbox groups and panel groups should always include a group label. However, there are some cases where hiding the group label can provide design flexibility or space for additional context. If the group label within the component build is hidden, include an alternate label elsewhere on the screen as well as within the code for accessibility.
<img src="https://design.visa.com/assets/components/checkbox/checkbox-hidden-labels.svg" alt="A checkbox group in a form with its label hidden. The checkbox group is within a question on the form that provides context about the checkbox group."/>

### Nested options
In some cases it may be appropriate to format checkbox groups with nested options. Users can select all nested options by selecting the parent or top-level checkbox, or unselect all nested options to by unselecting the parent checkbox. Alternatively, users can select nested options individually when the parent option is not selected. When the parent checkbox shows the indeterminate state, selecting it causes all nested options to be selected.
- Ensure all nested options are related to the parent option. 
- Use the unselected state for the parent option when all nested options are unselected.
- Use the selected state for the parent option when all nested options are selected. 
- Include a chevron UI icon button to enable users to expand and collapse the nested options.
<br/>
**Note:** The indeterminate state is not fully accessible for screen readers. To learn about alternative methods for nested checkbox groups, visit [Accessibility](https://design.visa.com/components/checkbox/accessibility).

#### Collapsed

The user selects the chevron UI icon button to reveal the nested options.
<img src="https://design.visa.com/assets/components/checkbox/checkbox-collapse.svg" alt="A checkbox group with a leading right pointing chevron. Options are hidden."/>
- Use the right pointing chevron to indicate collapsed content. 

#### Expanded
The user makes their selection from the available nested options. 
<img src="https://design.visa.com/assets/components/checkbox/checkbox-expand.svg" alt="A checkbox group with a leading down pointing chevron. Options are displayed."/>
- Use the downward pointing chevron to indicate expanded content. 

### Default selections
In general, checkboxes should be unselected by default to give users full control over their choices. The main exception is when a choice is required and the selection indicates a default or system setting. 

### Optional vs. required labels
Always ensure required fields are clearly labeled. While this may seem repetitive, it helps users scan for necessary information and reduces errors. There are two methods for labeling required fields based on your use case. Whichever method you select, use it consistently across your experiences. <br/><br/>
**Note:** Previous VPDS guidance recommended only marking optional fields. Our guidance has been updated to reflect current [Nielsen Norman Group](https://www.nngroup.com/articles/required-fields/)<!-- aria-label="Nielsen Norman Group (opens in a new tab)" --> recommendations. Learn more about optional vs. required labels in [Forms](https://design.visa.com/patterns/forms/#optional-vs-required-labels).

                    
              ### “Required” in the label (preferred method)
              
              <Typography variant="body-2">Including “required” within the label ensures it’s easy to find, particularly when instructions at the top might not be visible while scrolling. This method bolsters accessibility for both sighted and non-sighted users. </Typography>  
              
              <img src="https://design.visa.com/assets/components/checkbox/checkbox-mark-required.svg" alt="A checkbox group with its label marked as required"/>
              
              - Mark all fields that are required. This ensures you’re as explicit and transparent as possible.
              - Include “(required)” in field label with a space between the last word and the first parenthesis. 
                 
          
                    
              ### Asterisk in the label (alternative method)
              <Typography variant="body-2">
              Asterisks are commonly used to indicate required fields. The main advantage to using this method is that it doesn’t take up much space, helps users along a common edge, and can be used in addition to formatting hints in the label. 
              </Typography>
              
              <img src="https://design.visa.com/assets/components/checkbox/checkbox-asterisk.svg" alt="A checkbox with an asterisk in the label "/>
              
                - Always include a legend or key at the top of the content area noting that the asterisk indicates a required field.
                - Place the asterisk at the beginning of the label with a space between the symbol and the first word.
          
    

### When required is implied
Although it's usually recommended to label required fields, there are cases where it’s implied that the field is required. This is common when there’s a one or two fields fundamental to completing of a task, like the username and password fields on a login screen. In these cases, marking the fields required isn’t necessary but can add additional clarity.

### Labeling optional fields
It’s not generally necessary to mark which fields are optional. While doing so can support clarity, it also adds unnecessary visual noise. Whatever you choose, apply the choice consistently to avoid confusion.

## Content
- Always use sentence case except for proper nouns or acronyms.
- Use plain language and avoid abbreviations or jargon.
- Visit [Content](https://design.visa.com/content) for additional guidance on crafting content within apps and experiences. 

### Descriptions
- Use full sentences with proper punctuation.
- Limit descriptions to 80 characters or 20 words including spaces.

### Labels
- Don’t include punctuation.
- Ensure group labels accurately summarize the options available for selection.
- Limit labels to three words or fewer unless referencing proper nouns, such as product names. 
- Use [Parallel structure](https://design.visa.com/content/grammar/#parallel-structure) for labels across your experience, either starting with verbs such as “Select a notification preference” or nouns such as “Notification preferences”.

## Platform considerations
### Mobile
Checkboxes are available in mobile and web and should be implemented similarly on both platforms.
- Use checkbox panels to provide a larger touch area when necessary. 
- Use default checkboxes to save space and prevent user overload, especially when there are many checkbox groups used together in a form.
<img src="https://design.visa.com/assets/components/checkbox/checkbox-mobile.svg" alt="A checkbox panel group and checkbox group displayed in a mobile layout."/>


---

# accessibility

---
title: Chips
tab_order: 2
description: Compact elements used to filter content or display user input.
meta_description: Find accessibility guidelines for compact elements that filter content or display user input. 
thumbnail: assets/components/chip-graphic.svg
---

## Best practices

- Ensure all chips have an ID, which is used in the `for` attribute of the label, as selection chips are really checkboxes wrapped in labels.
- Always use an `aria-label` for removable chips, which are really buttons. Use a label such as "clear &lt;label text&gt;" to ensure screen reader users can predict the button’s behavior.
- Use a `fieldset` and `legend` to ensure chip groups are within HTML lists so screen readers can indicate how many options are in the group.

{/* CURSOR AND KEYBOARD */}

## Keyboard controls
Chips have the standard behavior for checkboxes (selection chips) or buttons (removable chips).

  ### Navigation

   Keyboard actions and their corresponding behaviors for navigation chips

- Key: Moves to next chip.

- Key: Moves to previous chip.

  ### Selection chips

   Keyboard actions and their corresponding behaviors for selection chips

- Key: Toggles beween on and off state.



---

# index

---
title: Chips
tab_title: Code
description: Compact elements used to filter content or display user input.
meta_description: Get code for compact elements that filter content or display user input. 
thumbnail: assets/components/chip-graphic.svg
categories:
  - selection-controls
---

## Component Code Examples: chip

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the chip component
const component = parsed.components.find(c => c.name === 'chip');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `chip`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Chips
description: Compact elements used to filter content or display user input.
meta_description: Learn how to use compact elements to filter content or display user input. 
keywords: ["Pills", "tags", "lozenges", "selectable tag", "dismissible tag"]
related:
  components:
    - checkbox
    - toggle-button
tab_order: 1
---

Chips are compact, interactive elements that represent an input or option. They often appear in groups helping users filter content, enter data, or complete tasks efficiently. 
<br/>
Also known as: Pills, tags, lozenges, selectable tag, dismissible tag.

## Anatomy

<img src="https://design.visa.com/assets/components/chips/chips-anatomy.svg" alt="A chip with callout A indicating the required label, another chip with an avatar and clear button with callout B indicating the optional avatar, and a third chip with a leading icon and clear button with callout C indicating the leading icon and callout D indicating the clear button."/> 

**A. Label (required):** Brief text describing the chip. <br/> **B. Avatar (optional):** Thumbnail image or logo representing users or entities. <br/> **C. Leading icon (optional):** Icon used to represent the chip. <br/> **D. Clear button (required):** Button used to deselect removable chips.

## Usage
  When to use and when not to use different types of chips

- Component: To enable users to filter content by selecting from a set of pre-determined chips. <br/> <br/> If there’s sufficient space to display all the available selection chips at once.
- When to use: If there is only one option. Consider using a [Default checkbox](https://design.visa.com/components/checkbox/usage) instead.

- Component: To provide a visual representation of options selected from a checkbox group or multiselect component. <br/><br/> For more complex filtering scenarios where only the selected options should be displayed in chips.
- When to use: If the list of options is brief or simple and it would be easier to select and deselct chips directly.

## Best practices
- Maintain consistent spacing and margins between chips to enhance readability and visual consistency. Reference [Scaling and reflow](https://design.visa.com/components/chips/usage/#scaling-and-reflow) for more guidance.
- Organize chips into logical groups to help users understand relationships between options or categories.

### Selection chips
Selection chips enable users to make choices by manually selecting a chip from a set or group. They can be used to filter content or indicate selected items. Selection chips are similar to checkboxes or toggle components, where clicking the chip selects it, and clicking it again deselects it. 

<img src="https://design.visa.com/assets/components/chips/chip-placement-below.svg" alt="Two selected chips below a search input field."/> 
- Clearly indicate when a chip is selected using color, a checkmark, or another visual indicator.
- Display all selection chips at once, including those that have been deselected.

### Removable chips
Removable chips represent selections by appearing once the user has selected an item from a checkbox group, multiselect component, or set of filters. They show brief information about each selection and provide an easy way for users to remove individual items. These chips provide a visual representation of items the user has selected, but aren’t selectable themselves.
 
<img src="https://design.visa.com/assets/components/chips/chips-placement-removable.svg" alt="An action bar with two input fields, an apply button, a clear filters button, and two removable chips shown below."/> 
- Always provide a clear button to remove chips.
- Always hide chip options after removal.
- Consider asking for confirmation before removal if the chip removal has significant impact.

#### Removable chip size

  Removable chips come in two sizes depending on their location, standard and compact. For both sizes, selecting the clear button will remove the chip.

              
      ##### Standard

      Standard-sized chips appear outside of components and display options or filters that have been applied by the user.  
      <img src="https://design.visa.com/assets/components/chips/chip-removeable-standard-size.svg" alt="A checkbox group with two items selected. The selected items are shown as chips below."/>  
      - Arrange chips in a logical order, such as by order of selection or alphabetically.
    

              
      ##### Compact 

      Compact chips appear inside components like input fields or comboboxes after user selection or input.         
      <img src="https://design.visa.com/assets/components/chips/chip-removeable-compact-size.svg" alt="A combobox and an input field and with compact chips inside of them."/>    
      - Keep chip labels concise to maintain readability and prevent truncation.
    
  

## Behaviors
Chips have various behaviors designed to enhance user interaction and functionality. This section provides guidance on the the expected behaviors of the chip variants, selection and removable chips.

### Selection chips
Selection chips toggle between selected and deselected stated when clicked by the user.

### Removable chips
 
Removable chips allow the user to perform one action on the chip, usually removing the settings from the list.

 

### Scaling and reflow
Scaling and reflow refers to how content behaves as the container size changes, particularly when the container is too small to display all content at once. This describes the behavior of chips as their number increases and they wrap in a container and how individual chips behave when their content is too long. 
- Display chip labels fully when possible.
- Maintain consistent spacing between chips during reflow.
- Keep chip labels concise to maintain readability and prevent truncation.

 

 ## Content
- Use clear, concise text to label chips.
- Use sentence case, except for proper nouns or acronyms.
- Use simple language - avoid abbreviations or jargon.
- Don’t include punctuation in chip labels.
- Limit chip labels to a 20-character maximum.


---

# accessibility

---
title: Color selector
tab_order: 2
description: Menu that allows users to select a specific color through a variety of ways.
meta_description: Find accessibility guidelines for menus that enable users to select a color using a variety of methods.
thumbnail: assets/components/color-selector-graphic.png
---

## Best practices

<br />
**Note:** A color selector is an `input type=&quot;color&quot;`. Our libraries use this HTML native element.  Browsers render those differently from each other. Color selectors  are handled by the browser so developers have limited amount of control over the component display and behavior, however, most of the work is done by the browser.
- Ensure an `input type=&quot;color&quot;` is labeled and associated with related content just as you would with other inputs.
- Consider using a tooltip with additional descriptions to accompany the color selector. Reference the [Color selector](https://design.visa.com/components/color-selector) examples and [Tooltip](https://design.visa.com/components/tooltip) for more.

## Keyboard controls

Keyboard actions and their corresponding behaviors for color selector

- Key: Moves focus to the next focusable element.<br/><br/>
                    When the color selector menu is expanded, all focusable elements in the menu are included in the tab sequence. Focus goes in a circular rotation within the menu, so if the the focus was on the last element, the next focus would move to the first interactive element.

- Key: Moves focus to the previous focusable element.<br/><br/>
                    When color selector menu is expanded, all focusable elements in the menu are included in the shift + tab sequence. Focus goes in a circular rotation within the menu, so if the the focus was on the first element, the next focus would move to the last interactive element.

- Key: Moves/pans the color well two-dimensional slider.<br/><br/>
                Moves/pans the eye-dropper window.

- Key: Moves left or right through the hue slider.

- Key: Spins the format toggler edit spin box channels - RGB/HSL/HEX.

- Key: Accepts the adjusted Color well/Eye dropper/Hue/RGB/HSL/HEX values and closes the Color selector menu.<br/><br/>
                    Prompts the eye-dropper button.<br/><br/>
                    Selects the eye-dropper window color.

- Key: Dismisses the Color selector menu if no color adjustments are made. If color adjustments are made, the first instance cancels any color adjustments, and then the second instance dismisses the Color selector menu.

- Key: RGB and HSL accepts digits or numerals. RGB and HSL have limits to their values.<br/><br/>
                For RGB input fields, each RGB value ranges between 0-255. Any numeral entry in the RGB input fields exceeding 255, accepts the first two digits numeral.<br/><br/>
                For HSL input fields, H (Hue) input field value ranges between 0-359 degrees; S (Saturation) and L (Lightness) values range between 0-100%.

- Key: For HEX input field, the format is #RRGGBB and the values range from 00 to FF for each color channel with total possible color combinations of 256 power 3 (16,777,216).



---

# index

---
title: Color selector
tab_title: Code
description: Menu that allows users to select a specific color through a variety of ways. 
meta_description: Get code for menus that enable users to select a color using a variety of methods.
thumbnail: assets/components/color-selector-graphic.png
categories:
  - inputs
  - selection-controls
---

## Component Code Examples: color-selector

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the color-selector component
const component = parsed.components.find(c => c.name === 'color-selector');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `color-selector`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples



---

# usage

---
title: Color selector
tab_title: Usage
tab_order: 1
description: Menu that allows users to select a specific color through a variety of ways.
meta_description: Learn how to implement menus that enable users to select a color using a variety of methods.
thumbnail: assets/components/color-selector-graphic.png
related:
  components:
    - input
  baseElements:
    - color
---

Color selectors are a built-in feature provided by the operating system or browser. They combine an input field with a menu, which is prompted by a button, allowing users pick a custom color. It's important to note that the design of this component has limited customizations since it's a native component.

## Anatomy

<img src="https://design.visa.com/assets/components/color-selector/color-selector-anatomy.svg" alt="Color selector with menu expanded"/>
**A. Swatch button (required):** Button that expands or collapses the color swatch menu while showing the color selected.<br/>
**B. Label (optional):** Text summarizing the purpose of the color selector.<br/>
**C. Tooltip inline message (required):** Text providing color code instructions.<br/>
**D. Accessibility tooltip button (required):** UI icon button that reveals the tooltip inline message on hover.<br/>
**E. Color range (required):** Gradient area allowing users to manually select a specific color from the range.<br/>
**F. Eyedropper (required):** Tool allowing users to sample a color from anywhere on the screen using the OS color selector.<br/>
**G. Color hue slider (required):** Area below the gradient box that allows users to adjust the hue of the selected color.<br/>
**H. Input (required):** Text field appearing in the expanded menu section that enables users to enter color codes.<br/>
**I. Toggle button (required):** Toggle button allowing users to toggle between RGB, HSL, and HEX color codes.<br/>
**J. Swatch preview (required):** Preview window showing the color selected.

## Best practices
- Follow the default appearance and interaction of the  [Select](https://design.visa.com/components/select/usage) component on different browsers.
- Use this component in areas of your app where you want to allow users to customize color.
- For more information about using inputs, visit [Input](https://design.visa.com/components/input/usage) guidelines.

### Default color selector
Color selectors leverage the native appearance of different browsers and operating systems, meaning it has limited customizations available.
<img src="https://design.visa.com/assets/components/color-selector/color-selector.svg" alt="Native color selector in Google Chrome browser"/>
- Always test the color selector on multiple browsers and devices to ensure consistent user experience.

    
        #### Collapsed
        When collapsed, the color selector typically appears as a small rectangle that previews the selected color.
        <img src="https://design.visa.com/assets/components/color-selector/color-selector-collapsed.svg" alt="A collpased color selector with just the color swatch button and label showing"/>
        - Allow users to expand the menu by selecting anywhere in the swatch.
    
    
        #### Expanded
        When expanded, the menu displays a range of selection methods the user can use to adjust the color. 
        <img src="https://design.visa.com/assets/components/color-selector/color-selector-expanded.svg" alt="An expanded color selector with menu showing"/>
        - Allow users to collapse the menu by removing focus from the menu. 
    

### Hidden labels
Color selectors should typically include a label. However, there are some cases where hiding the label can provide design flexibility or space for additional context. If the label within the component build is hidden, include an alternate label elsewhere on the screen as well as within the code for accessibility.
<img src="https://design.visa.com/assets/components/color-selector/input-bp-text-icon.svg" alt="An array of collapsed color selectors indicating brand and text colors can be changed"/>
- Always include a label somewhere else on the screen if you choose to omit it from the component build. 
- Always include the label programmatically to ensure screen reader users have the full context.

### Accessibility tooltip
The accessibility tooltip provides visually impaired users with valuable information about the acceptable ranges for each color code format. Users can activate the tooltip by hovering over the icon button, and close it by simply shifting focus away.
<img src="https://design.visa.com/assets/components/color-selector/tooltip.svg" alt="A tooltip providing acceptable ranges for each color code format is activated"/>

## Behaviors

### Pre-selected color
In general, color selectors will have a pre-selected color of black (#000000) by default. However, this can be changed to a different default color on page load to increase usability and provide users with hint about how their selection will be applied.
<img src="https://design.visa.com/assets/components/color-selector/pre-selected-color.svg" alt="An array of collapsed color selectors indicating certain colors can be changed along with a button to reset colors to the default color."/>
- Provide users with a way to reset the color selection if they wish to revert to the default color.
- Use descriptive labels to give users context on how their selection will be applied.

### Selection method
The color selector allows users to change the color in a variety of ways including inputting a color code, adjusting the color range and hue slider, and using the eyedropper tool. The swatch preview will display the color selected currently.

#### Color code input

The color value input allows users to enter a value by editing the input text fields within the expanded menu. Users can use the arrow toggle to change between RGB, HSL, or HEX color codes. 
<img src="https://design.visa.com/assets/components/color-selector/color-value-toggle.svg" alt="A toggle button is pressed to switch between HEX and RGB value inputs"/>
- The color preview indicators will actively change color as the user types in their color values.

#### Hue slider and color range

The color range and hue slider allow users to select a color and are often used in combination. The hue slider is used as a macro-selector to choose a color, while the color range is a micro-selector to adjust the lightness and darkness of the selected color.
<img src="https://design.visa.com/assets/components/color-selector/color-range-hue-slider.svg" alt="A color hue slider and color range"/>
- Allow users to close the color selector menu by removing the focus from the menu.

#### Eyedropper tool

The eyedropper tool allows users to select a specific color that exists on any given page without having to enter a color value or guess what color it is on the color range.
<img src="https://design.visa.com/assets/components/color-selector/eyedropper.svg" alt="An eyedropper tool being used to select a color on a screen"/>
- Allow users to close the eyedropper by either selecting a color or pressing the ESC key.

## Platform considerations

### Web
Color selector components are only available for web.

<img src="https://design.visa.com/assets/components/color-selector/color-selector-desktop.svg" alt="Color selector with menu expanded"/>

---

# accessibility

---
title: Combobox
tab_order: 2
description: Dropdown menu that helps users enter text or select items from a list. 
meta_description: Find accessibility guidelines for dropdown menus that help users enter text or select an item from a list.
thumbnail: assets/components/select-combobox-graphic.svg
---

## Best practices

<br/>
**Note:** Comboboxes are comprised of multiple components. Many of the attributes that comboboxes use are handled by our library components. As with other form components, use `id` values to associate  additional instructions or error messaging so screen readers will read them. Reference [the coded examples.](https://design.visa.com/components/combobox)<!-- aria-label="combobox code examples" --> 
- Consider implementing a “no results found” message similar to the Angular examples.
- Visit [Listbox](https://design.visa.com/components/listbox) for notes on its roles which include `role=&quot;listbox&quot;`. 

## Keyboard controls

### Input

Maintain common keyboard shortcuts used for editing text unless uniquely specified. Refer to [Input](https://design.visa.com/components/input/accessibility) for details.
Keyboard actions and their corresponding behaviors for input

- Key: Moves to next interactive focusable element.

- Key: Moves to previous input field.

- Key: Opens the menu.

- Key: Opens the menu.

- Key: Dismisses menu and clears any inline autocomplete while maintaining user-entered input.

### Menu (listbox pop-up)

Reference [Listbox](https://design.visa.com/components/listbox/accessibility) for detailed interactions. Focus will loop in a circular direction among the menu items.

 Keyboard actions and their corresponding behaviors for menu (listbox popup)

- Key: Confirms the option in focus as the user’s selection and closes the menu.

- Key: Dismisses the menu, moves to next interactive focusable element.

- Key: Moves focus between the options in the menu.

- Key: Dismisses menu and clears any inline autocomplete while maintaining user-entered input.



---

# index

---
title: Combobox
tab_title: Code
description: Dropdown menu that helps users enter text or select items from a list.
meta_description: Get code for dropdown menus that help users enter text or select an item from a list.
thumbnail: assets/components/select-combobox-graphic.svg
categories:
  - selection-controls
  - inputs
---

## Component Code Examples: combobox

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the combobox component
const component = parsed.components.find(c => c.name === 'combobox');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `combobox`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Combobox
tab_title: Usage
tab_order: 1
description: Dropdown menu that helps users enter text or select items from a list.
meta_description: Learn how to use dropdown menus that help users enter text or select an item from a list.
keywords: ["Combo box", "autocomplete", "autosuggest", "UIPickerView (iOS)", "Spinner (Android)", "Menu (Android)", "MenuItem (Android)"]
related:
  components:
    - input
    - listbox
    - multiselect
  patterns:
    - forms
---

Comboboxes enable users to select one option from a menu or input custom text. This component combines an input field and single-select listbox to ensure users can find and select an option quickly.
<br />
Also known as: Combo box, autocomplete, autosuggest, UIPickerView (iOS), Spinner (Android), Menu (Android), MenuItem (Android).

## Anatomy

<img src="https://design.visa.com/assets/components/combobox/combobox-anatomy.svg" alt="Two combobox examples, one collapsed and one expanded. The collapsed combobox has 4 callouts. A is pointing to a label just above the combobox. B is the input field or main area. C is text just below. D is an arrow on the right side of the input field that is pointing down. The expanded combobox has 4 callouts. E is a magnifying glass icon to the left of the input field. F is a small round X button on the right side of the input field. G is the menu flyout. H is an option on the menu flyout."/>

**A. Label (required):** Text summarizing the options available for selection. <br/> **B. Input (required):** Text field enabling users to enter custom text or filter menu options. <br/> **C. Inline message (optional):** Brief text describing the field label in more detail. <br/>**D. Chevron icon button (optional):** UI icon button that expands or collapses the menu.<br/>**E. Leading icon (optional):** Visual indication that the input field is interactive.<br/>**F. Clear text button (optional):** UI icon button that clears the text input or selected option. <br/>**G. Menu (required):** Container displaying the list of options that includes scrollbar as needed.<br/> 
**H. Option (required):** Selectable text representing a single option.

## Usage
  When to use and when not to use combobox component

- When to use: To present a list of options where users can select only one.
- When not to use: If users can select multiple options from the list. Use [Multiselect](https://design.visa.com/components/multiselect) instead.

- When to use: For long lists where all options can't be viewed at once or require scrolling.
- When not to use: For short lists where all options can be viewed without scrolling. Use a [Radio button group](https://design.visa.com/components/radio) instead.

- When to use: If users would benefit from entering text to filter or search the list options.
- When not to use: If list options are unfamiliar and users wouldn’t benefit from searching for specific terms. Use [Select (native)](https://design.visa.com/components/select) instead.

- When to use: If space is limited and displaying options in a collapsible menu would help.
- When not to use: To present a list of actions. Use a [Dropdown menu](https://design.visa.com/components/dropdown-menu) instead.

## Best practices
- Ensure the selected option appears visually different from unselected options by using an icon and selected state. 
- Ensure users can select anywhere within an option label to select an option.
- List options in a logical order, either alphabetically or according to the most common or likely selection.
- Ensure comboboxes appear collapsed on page load to save space.

### Clear text button
Clear text buttons allow users to clear their input or selection from the field. 
<img src="https://design.visa.com/assets/components/combobox/combobox-bp-clear.svg" alt="A combobox component with a clear text button appearing when there is input typed."/>
- Only display the clear text button when the user is actively inputting text to prevent confusion or accidental clearing.

### Chevron direction
The chevron UI icon button enables users to manually expand or collapse the menu. The direction it points should indicate what happens when it’s selected.

                    
              #### Collapsed

              The chevron should point down when the menu is collapsed.
              <img src="https://design.visa.com/assets/components/combobox/combobox-chevron-collapse.svg" alt="A collapsed combobox with a downward pointing chevron"/>
              - Ensure the chevron icon can be used to manually expand the menu when selected.      
          
                    
              #### Expanded
              
              The chevron should point up when the menu is expanded. 
              <img src="https://design.visa.com/assets/components/combobox/combobox-chevron-expanded.svg" alt="An expanded combobox with an upward pointing chevron."/>
              - Ensure users can collapse the menu by removing focus from the field, not just by using the chevron icon.      
          

### Leading icons
Leading icons are placed at the beginning of an input field and are not interactive. They visually indicate the type of information required, such as an avatar for selecting a recipient. 
 <img src="https://design.visa.com/assets/components/combobox/combobox-icons.svg" alt="A collapsed combobox labelled Recipient with an icon of a person to the left of the input field"/>
- Use one leading icon per input field as multiple icons can confuse users.
- Use icons that are universally understood and directly relate to expected entry.
- Use leading icons consistently across experiences to help users learn and predict behavior.

### Pre-selected options
In general, all comboboxes should appear empty by default. This ensures users have full control over their choices and prevents confusion that a selection has already been made. When possible, leave all options unselected both visually and programatically. <br/><br/>
Some browsers require an option to be selected by default. If this occurs, the first option can be used as a placeholder that can’t be selected by the user. For required fields, leaving the placeholder option selected causes an error during submission. For optional fields, no error is shown. This ensures users must make an active choice and can’t accidentally submit the placeholder option. 

<img src="https://design.visa.com/assets/components/combobox/combobox-disabled.svg" alt="A combobox in which the first option is placeholder text saying 'Select an option.'"/>
- Use disabled styling so the placeholder option is visually distinct from the others. 
- Ensure placeholder text is clear and helpful to avoid confusing or frustrating the user. 
- Ensure placeholder text uses a font color with a 4:5:1 contrast ratio. 

### Empty state
An empty state occurs when when text entered in the input field doesn't match the available options within the menu.
<img src="https://design.visa.com/assets/components/combobox/combobox-empty-state.svg" alt="A combobox returning 'No results found.' "/>
- Use clear language to inform users that their input doesn’t match any options, as users may misinterpret an empty state for a loading state and wait for options to appear.

### Optional vs. required labels
Always ensure required fields are clearly labeled. While this may seem repetitive, it helps users scan for necessary information and reduces errors. There are two methods for labeling required fields based on your use case. Whichever method you select, use it consistently across your experiences. <br/><br/>
**Note:** Previous VPDS guidance recommended only marking optional fields. Our guidance has been updated to reflect current [Nielsen Norman Group](https://www.nngroup.com/articles/required-fields/)<!-- aria-label="Nielsen Norman Group (opens in a new tab)" --> recommendations. Learn more about optional vs. required labels in [Forms](https://design.visa.com/patterns/forms/#optional-vs-required-labels).

                    
              ### “Required” in the label (preferred method)
              
              <Typography variant="body-2">Including “required” within the label ensures it’s easy to find, particularly when instructions at the top might not be visible while scrolling. This method bolsters accessibility for both sighted and non-sighted users. </Typography>  
              
               <img src="https://design.visa.com/assets/components/combobox/combobox-mark-required.svg" alt="A combobox with its label marked as required"/>
              
              - Mark all fields that are required. This ensures you’re as explicit and transparent as possible.
              - Include “(required)” in field label with a space between the last word and the first parenthesis. 
                 
          
                    
              ### Asterisk in the label (alternative method)
              <Typography variant="body-2">
              Asterisks are commonly used to indicate required fields. The main advantage to using this method is that it doesn’t take up much space, helps users along a common edge, and can be used in addition to formatting hints in the label. 
              </Typography>
              
              <img src="https://design.visa.com/assets/components/combobox/combobox-asterisk.svg" alt="A combobox with an asterisk in the label "/>
              
                - Always include a legend or key at the top of the content area noting that the asterisk indicates a required field.
                - Place the asterisk at the beginning of the label with a space between the symbol and the first word.
          
    

### When required is implied
Although it's usually recommended to label required fields, there are cases where it’s implied that the field is required. This is common when there’s a one or two fields fundamental to completing of a task, like the username and password fields on a login screen. In these cases, marking the fields required isn’t necessary but can add additional clarity.

### Labeling optional fields
It’s not generally necessary to mark which fields are optional. While doing so can support clarity, it also adds unnecessary visual noise. Whatever you choose, apply the choice consistently to avoid confusion.

## Behaviors
Comboboxes can be implemented in a variety of ways to help users easily find and select an option. Reference the guidance below to learn about features of this component and optional behaviors you may implement based on use case. <br/><br/>

**Note:** This section introduces features that aren’t automatically included in the component design and can be implemented in various ways. Product teams can determine how to load and filter data for their use case and should work closely with developers and designers to determine the appropriate level of complexity for their product.

### Input and menu functionality
Input fields in combobox components can be implemented with a variety of methods that help users find and select menu options. Product teams should work with their designers and developers to choose the appropriate method for their use case. 

#### Manually expandable menu

Comboboxes can be implemented with menus that display all the selectable options upon expansion. In this method, the user can select an option from the menu without typing in the input field. The input field can optionally be implemented with a search or filter feature. Learn more about these below. 
<img src="https://design.visa.com/assets/components/combobox/combobox-manual-menu.svg" alt="A combobox showing the same list of options in the expanded menu when nothing is typed and when part of a word is typed."/>
- Include the chevron UI icon button to enable users to expand the menu without typing. 
- Implement optional user input with a search or filter behavior to help users find options. 

                    
              ##### Menu search
              In this method, the text field is used to search the options displayed in the menu. When the user types, the menu jumps so the option that matches their input best appears at the top of the field, and focus is placed on that option. 
              <img src="https://design.visa.com/assets/components/combobox/combobox-menu-search.svg" alt="Combobox with Visa data typed into it. The menu shows Visa Data Exchange is highlighted and is the first option, with Visa Account Updater and Visa B2B Connect below"/>
              - Only show the clear text button when the input field is in focus to prevent users from accidentally clearing their input.
              - Use this method when users may want to browse options that are similar to their input but don’t match exactly.      
          
                    
              ##### Menu filter
              In this method, the text field is used to filter the options displayed in the menu. When the user types, the options displayed in the menu are temporarily reduced so only those matching the entry remain.
              <img src="https://design.visa.com/assets/components/combobox/combobox-menu-filter.svg" alt="A combobox with Visa data typed into it. The only option in the menu is Visa Data Exchange and it is highlighted."/>
                - Include the clear text icon to enable users to remove their text input and return the menu to its original state without collapsing the menu. 
                - Use this method when users are likely to know exactly what option they’re looking for. 
          
    

#### With custom input

Comboboxes can also be implemented to accept custom input, which means users can create a custom option that isn’t available in the menu. This method is particularly helpful for providing flexibility when you can’t predict all potential inputs. <br/><br/>
When implementing comboboxes that accept custom input, ensure field accepts flexible formatting to avoid frustrating users with errors.  If the system can’t accommodate varying formats, use a pre-defined menu without custom input. To learn more, reference [flexible input](https://design.visa.com/components/input/usage/#flexible-input).

<img src="https://design.visa.com/assets/components/combobox/combobox-custom.svg" alt="A combobox with 1000 Main Str typed into it and the menu is filled with addresses that start with that text. To the left is the combobox with the address typed as 1000 Main Street, Chicago, IL and there is no menu"/>
- Pair this functionality with a filtering behavior like autosuggest or autocomplete so users can tell if their input matches a pre-defined option. 
- Only show the clear text button when the input field is in focus to prevent users from accidentally clearing their selection.

#### Input-prompted menu

Comboboxes can be implemented with a menu that only appears after the user enters text in the input field. This method is generally used for complex scenarios where a large number of options are available and can’t all be displayed immediately. <br/><br/>
It’s common to implement this type of combobox with autocomplete or autosuggest. To learn more, reference [Input](https://design.visa.com/components/input/usage). 

<img src="https://design.visa.com/assets/components/combobox/combobox-input-prompted.svg" alt="A Search combobox has a search leading icon and no arrow to indicate a menu. The same combobox then has Direct typed into is and there is now a menu with options such as direct deposit, direct deposit election, direct deposit guide, and so on."/>
- Consider including a leading icon to indicate the purpose of the input field. 
- Only show the clear text button when the input field is in focus to prevent users from accidentally clearing their input.
- Don’t include a chevron icon, even when the menu is open. Users can collapse the menu by removing focus from the field. 

### Selection method
Users can select an option using one of the following methods that aim to simplify the process and prevent accidental selections. Selection methods can be combined with search, filter, or autocomplete/autosuggest behaviors to create custom interactions. Consider your desired filtering behavior when implementing a selection method, as filtering behaviors affect how and when focus is placed on a menu option. 

#### Manual selection (preferred)

Select and confirm requires users to confirm their choice before it's displayed in the field. When the user places focus on an option within the menu, it won't appear as the selected value in the field until the user selects the option they want by clicking or using the enter key. This is the preferred method as it’s the most accessible and provides users full control over their selection. 
<img src="https://design.visa.com/assets/components/combobox/combobox-manual.svg" alt="A combobox with the menu expanded and no text entered. The option Technology is highlighted. The same combobox with a mouse cursor over Technology now has a gray background and checkmark next to it, as well as Technology appearing in the text input."/>
- Ensure the selected option isn't displayed until the user confirms their choice. This prevents accidental selection and gives users the opportunity to change their mind before submission.

<Typography id="automatic-selection" tag="h4" variant="subtitle-1">Automatic selection</Typography>

Automatic selection doesn’t require the user to confirm their choice before it’s displayed in the field. When focus is placed on an option in the menu, it automatically appears as the selected value when the user tabs out of the menu or removes focus from the combobox as a whole. <br/><br/>
While this method can provide a streamlined selection process, it’s not as accessible as manual selection. Product teams using this method are responsible for ensuring accessibility standards and practices are met. 
<img src="https://design.visa.com/assets/components/combobox/combobox-auto-select.svg" alt="A combobox with the menu expanded and Technology is highlighted. The same combobox collapsed with Technology in the text input field."/>
- Ensure the selected option isn't displayed until the user confirms their choice. This prevents accidental selection and gives users the opportunity to change their mind before submission.

### Scaling and reflow
Scaling and reflow refers to how content behaves as the container size changes, particularly when the container is small and can’t display all content at once. This is common with comboboxes, as they’re often used when screenspace is limited. While the option menu can scale vertically, the input field has a fixed height. 
- Scale the option menu vertically until the maximum height is reached. 
- Implement a scroll bar when the maximum height is reached to enable users to access all the options. 

## Content
- Always use sentence case except for proper nouns or acronyms.
- Use plain language and avoid abbreviations or jargon.
- Reference [Content](https://design.visa.com/content) for additional guidance on crafting content within apps and experiences. 
- Avoid using unnecessary articles like “the” or “an”, unless they’re included in the proper name of a product or service.  

### Labels
- Limit field labels to three to five words when possible.
- Be consistent when using plural language or “(s)” in field labels. For example, use “Select card type,” “Select card types,” or “Select card type(s)” consistently. If using “(s),” use the asterisk method over “(required)” to keep labels concise. 
- Use parallel structure across field labels, using either nouns like "Services" or verbs like "Select a service". Learn more about parallel structure in [Grammar and punctuation](https://design.visa.com/content/grammar#parallel-structure).

### Option labels
- Limit option labels to three words or fewer unless referencing proper nouns, such as product names. 
- Avoid using unnecessary articles like “the” or “an,” unless they’re included in the proper name of a product or service.  

### Inline messages
- Use full sentences with proper punctuation. 
- Limit descriptions to 80 characters or 20 words including spaces.
- Provide useful information such as why a field is required (if not obvious) without being technical.
- Give an example or specific syntax or values for inputs to help avoid errors.

#### Inline error message

- Use inline error messages to draw attention to errors without causing frustration.
- Provide clear, prescriptive guidance on correcting the error. Avoid redirecting users to another page to fix it. 
- Communicate whether the problem can occur again and offer an alternative backup solution in case it does. 

## Platform considerations

### Mobile
On mobile screens, the combobox opens as a full-screen and spans the width of the page. Once users make a selection, the fullscreen view closes automatically and the user is returned to their place in the form. 

<img src="https://design.visa.com/assets/components/combobox/combobox-platform-mobile.svg" alt="A form in mobile view has a combobox. When the combobox is expanded, the main heading at the top of the view becomes the label of the combobox and has an X button next to it. Below is the text input field and the rest of the view is filled with the menu options."/>
- Ensure users can exit the fullscreen view by selecting the close button in the top app bar. 
- Remove the chevron icon button from the input field when the combobox is in fullscreen view.


---

# accessibility

---
title: Content card
description: Compact displays that summarize or direct users to more information.
meta_description: Find accessibility guidelines for compact displays that summarize or direct users to more information. 
thumbnail: assets/components/content-card-graphic.svg
tab_order: 2
---

## Best practices

- Ensure buttons and links have meaningful `aria-labels` if there are multiple content cards with generic link or button labels. For example, use “close cardA” so a screen reader will announce which card the button goes to.
- Ensure clickable cards don’t have additional controls like a close button, as the whole card is a button. 
- Consider using an HTML heading element for each card to help with keyboard navigation and page summaries for screen readers. Be sure to use the right heading level for the hierarchy of the page so that there aren’t skipped levels, even if you style the heading to look like a different level.

## Keyboard controls

Keyboard actions and their corresponding behaviors for content cards

- Key: Prompts the default action associated with a button.

- Key: Moves to the next focusable element.

- Key: Moves to the previous focusable element.



---

# index

---
title: Content card
tab_title: Code
description: Compact displays that summarize or direct users to more information.
meta_description: Get code for compact displays that summarize or direct users to more information. 
thumbnail: assets/components/content-card-graphic.svg
categories:
  - structure-and-layout
---

## Component Code Examples: content-card

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the content-card component
const component = parsed.components.find(c => c.name === 'content-card');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `content-card`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Content card
description: Compact displays that summarize or direct users to more information.
meta_description: Learn how to use compact displays that summarize or direct users to more information. 
keywords: ["Tile", "card", "snapshot", "spotlight"]
related: 
  baseElements:
    - responsive-grid-system
  charts:
    - charts/overview
tab_order: 1
---

Content cards are stylized containers that group elements and actions for a single, related subject. As one of the most customizable components, they can be tailored to meet specific user needs or preferences. Content cards are often displayed within a page's content area and provide a preview or summary of another page's content to encourage users to click-through for more details. They are often presented in multiples, offering various topics or aspects for users to explore.
<br />
Also known as: Tile, card, snapshot, spotlight.

## Anatomy

<img src="https://design.visa.com/assets/components/content-card/card-anatomy.svg" alt="A content card with callout A indicating the required card, callout B indicating the optional icon, callout C indicating the optional card title, callout D indicating the optional subtitle, callout E indicating the optional body text, callout F indicating the optional button or link, callout G indicating the optional UI icon button, and callout H indicating the optional image"/> 

**A. Card (required):** Container featuring related content, icons, images, and actions. <br/> **B. Icon (optional):** Static icon enhancing or communicating the meaning of the card. <br/> **C. Card title (optional):** Brief text summarizing the subject of the content card. Can be used with or without the subtitle. <br/> **D. Subtitle (optional):** Additional text communicating more details. Can be used with or without the card title. <br/> **E. Body text (optional):** Brief message detailing important information about the content card. <br/> **F. Button or link (optional):** Text button and/or link that prompts an action or directs users to relevant resources. <br/> **G. UI icon button (optional):** Visual representation of an action that doesn’t require text to convey meaning. <br/> **H. Image (optional):** Graphic, illustration, or photography representing or communicating the meaning of the card.

## Usage

When to use and when not to use different types of content cards

- Component: To provide information and actions related to a single subject.
- When to use: To display large amounts of information or information that isn’t related. <br/><br/> As a [Dialog](https://design.visa.com/components/dialog/usage) or modal, as content cards do not float over the main content area of a page.

- Component: To make the entire card selectable.
- When to use: If no additional information or actions are associated with the card.

- Component: To save space on small screens.
- When to use: For detailed information that’s difficult to read in a small format.

- Component: To represent simple data visualizations.
- When to use: For complex or interactive data visualizations without customizing. While the dashboard card can serve as a starting point, it may require additional design iteration to represent more intricate data visualizations.

## Best practices

- Use consistent elements for cards within the same layout or content area to help users scan and understand information.
- Establish a clear visual hierarchy within the container to enhance scannability and readability.
- Use visuals such as icons, images, or illustrations to enhance the meaning and aid in quick comprehension of the content.
- Avoid cluttering the card with too many elements or actions. Keep the design simple and focused on the primary task.

### Icons and images

Icons and images add visual interest and enhance the meaning of content cards. By integrating relevant icons and images, you can quickly and effectively convey the essence of the content. 
- Avoid overloading a card with too many elements that detract from the main message.
- Always ensure visuals align with the content and support the user's understanding.

#### Icons
             
Icons can be used to add visual interest or enhance the meaning of the card.  
                      
<img src="https://design.visa.com/assets/components/content-card/card-bp-icons-1.svg" alt="A content card with an icon of a blue lock, titled 'Auto-lock activated', body text 'Auto-lock disables your dashboard after two minutes without activity.', and a button labelled 'Disable auto-lock'."/>
      
- Use universally recognized icons to ensure comprehension for all users.
- Use one icon per card to maintain simplicity and avoid confusion.  

#### Category icons
           
Icons and labels can be used to categorize specific subjects under a broader subject.  

<img src="https://design.visa.com/assets/components/content-card/card-bp-icons-2.svg" alt="A content card with a Finances category label and icon, titled 'User profile', subtitled 'Manage your account', body text 'Access card services, security settings, contact information, and more.', a button labelled 'Manage settings', and a link labelled 'Learn more'."/>
             
- Use distinct and descriptive category names and icons for easy identification.
- Use one icon per category card to ensure it clearly represents and differentiates each category.           

#### UI icon buttons
             
UI icons buttons visually represent an action without text. They’re typically used for actions related to the entire card.  
                      
<img src="https://design.visa.com/assets/components/content-card/card-bp-icons-3.svg" alt="A content card titled 'Get the latest insights' with a download UI icon button, body text 'Explore new online spending trends in the Customer Spending Report.', a numerical value '2,234', and '12% increase' with a black arrow pointing up."/>
      
- Ensure icons clearly and intuitively indicate the action they represent without accompanying text.
- Make sure UI icons are large enough to be usable, especially on touch devices.  

#### Images
           
Images such as illustrations and photography add visual interest and meaning to content cards.   

<img src="https://design.visa.com/assets/components/content-card/card-bp-images.svg" alt="A content card with an image of a male and female sitting on a couch viewing their laptop with a dog next to them, titled 'Visa Secure, subtitled 'Peace of mind with every purchase', body text 'Get advanced security for your online purchases. With Visa Secure, purchasing online is as secure as a buying in a store.', a button labelled 'Sign up', and a link labelled 'Learn more'."/>
             
- Only use images when relevant or to enhance the understanding of the content.
- Avoid using intricate illustrations that may not be clear on smaller screens.           

### Dividers and borders

Dividers and borders can be used to enhance the visual appeal and readability of content-heavy cards by breaking down dense information and improving organization.

#### Content dividers
             
Dividers can be added between content to break up sections or give the card a sense of hierarchy.  
                      
<img src="https://design.visa.com/assets/components/content-card/card-bp-divider.svg" alt="A content card with a shipping truck icon, a divider between the title 'Same-day shipping' and description 'Unlock free same day shipping when you spend over $100.', and a link 'Learn more'."/>
      
- Use dividers to provide a clear separation and organize information for easy consumption.
- Place dividers in consistent areas across content cards used in your experiences.   

#### Card borders
           
Borders can be added to the bottom for emphasis or as a hover state to indicate the entire card is clickable.   

<img src="https://design.visa.com/assets/components/content-card/card-bp-border.svg" alt="A content card with a Installments category label and icon, titled 'Buy now, pay later', body text 'Just select the installments option at checkout so you can pay over time.', a link 'Learn more', and a blue bottom border."/>
             
- Use color to further distinguish multiple cards in a group, such as category cards. 
- Use bottom borders consistently across content cards used in your experiences.           

### Card collections

Content cards are typically presented as a grid or collection, reading left right, with each card the same size. For more complex grids, like the one below, reading order should follow a left to right, top to bottom pattern. The layout of these groups can influence user perception, so they should be organized for easy scanning and understanding. 

<img src="https://design.visa.com/assets/components/content-card/card-collection-read-order.svg" alt="A collection of content cards numbered from one to six with arrows showing the read order, emphasizes order depending on languages"/>

- For left-to-right languages, the order should go from top left to bottom right.
- For right-to-left languages, the order should go from top right to bottom left.

## Behaviors

### Clickable card elevation

On hover, a clickable card may transition from a small to medium elevated surface. The default surface for content cards has a 1px border, small elevation, and a background of Surface 1. Surfaces are intended to be customizable to the individual needs of an application, as styling needs will change based on number of cards and desired emphasis. 

<img src="https://design.visa.com/assets/components/content-card/card-behaviors-elevation.svg" alt="A content card shown with the default small elevated surface next to a content card shown on hover with the medium elevated surface"/>

## Platform considerations

### Responsive scale and reflow

Content cards scale to adapt to different screen sizes, and their position and alignment can also change. Content card layouts may be fluid or fixed width. When used in a fluid grid, a card’s width can adjust across grid columns and rows. 
<br />
Content will also resize and reflow accordingly. Some content may not be appropriate to resize due to limitations or visual distortion. Learn more by visiting [Responsive grid system](https://design.visa.com/base-elements/responsive-grid-system).

#### Fixed grid

<img src="https://design.visa.com/assets/components/content-card/card-platform-fixed.svg" alt="Desktop and tablet screens with collections of content cards noting the card's widths being fixed to the grid width"/>

#### Fluid grid

<img src="https://design.visa.com/assets/components/content-card/button-platform-fluid.svg" alt="Desktop and tablet screens with collections of content cards noting the card's widths adjust with the grid width"/>



---

# accessibility

---
title: Date and time selectors
tab_order: 2
description: Interactive calendar or time selector that allows users to choose a specific date or time.
meta_description: Find accessibility guidelines for interactive calendar or time selectors that allow users to choose a specific date or time. 
thumbnail: assets/components/date-selector-graphic.svg
---

## Best practices

<br/>
**Note:** Date and time selectors are inputs with `type=&quot;date&quot;` or `type=&quot;time&quot;`. Our libraries use these HTML elements, so different browsers will show this component differently. As a result, developers have a limited amount of control over how these elements appear and behave.
- Always label `input type=&quot;date&quot;` and `input type=&quot;time&quot;` elements and associate them with related content.

## Keyboard controls
VPDS date and time selectors share keyboard behavior with text inputs. The special date and time menus are controlled by the browser. 

### Input field

Reference [Text field](https://design.visa.com/components/input/accessibility) and [Button specs](https://design.visa.com/components/button/accessibility) for base behavior. 

Keyboard actions and their corresponding behaviors for input field

- Key: Moves between the date fields mm/dd/yyyy and adjust the entries within those fields.

- Key: Moves between the date fields mm/dd/yyyy and adjust the entries within those fields.

- Key: Accepts all valid characters.

- Key: Opens the date selector menu and places focus on the selected date displayed in the input text field. <br/><br/> If no date has been selected, it places the focus on the current date.

#### Date selector menu

Keyboard actions and their corresponding behaviors for date selector menu

- Key: Closes the menu and moves the focus back on menu-prompting element. <br/><br/> If the focus or hover was set to a different menu item, closing the menu with Esc will not update the selection.

- Key: Moves the focus to the next item of the tab sequence within the date selector menu. <br/> <br/> **Note:** Only one button within the calendar grid is in the tab sequence. The focus will loop back to the top (Month and year label) when the focus is on the last button (Today).

- Key: Moves the focus to the previous item of the tab sequence within the date selector menu. <br/> <br/> **Note:** Only one button within the calendar grid is in the tab sequence. Focus will loop back to the bottom (Today) when the focus is on the first button (Month and year label).

#### Date selector menu: Dates grid

Keyboard actions and their corresponding behaviors for date selector menu: dates grid

- Key: Selects the date receiving focus, places focus back on the menu-prompting element, and updates the text field to display the selected date.

- Key: Moves the focus to the next menu item. The focus moves based on the set grid. ←→ moves the focus to the previous or next day incrementally.<br/><br/> If the focus is on the last day of the week, pressing → moves the focus to the following day. For example, if the focus was on the end of the week, pressing → shifts the focus to the following start of the week. <br/><br/> ↑↓ moves the focus to the previous or next week, on the same day of the week.

- Key: Home key moves the focus to the first day of the current week.<br/> <br/> End key moves the focus to the last day of the current week.

- Key: Page Up key changes the grid of dates to the previous month.<br/> <br/> Page Down key changes the grid of dates to next month.<br/> <br/> Set focus to the same date. If that day does not exist, then move focus to closest available date. For example, for dates that don’t exist within all months, such as the 29, 30, and 31, move the focus to the last date of the month.

#### Date selector menu: Month and year label and navigation buttons

Keyboard actions and their corresponding behaviors for date selector menu: month and year label and navigation buttons

- Key: Changes the month and/or year displayed in the calendar grid.

#### Clear button

Keyboard actions and their corresponding behaviors for clear button

- Key: Space or enter key on the Clear button closes the date selector menu, reset the month, date, and year in the input, and return the focus to the menu-prompting element.

#### Today button

Keyboard actions and their corresponding behaviors for today button

- Key: Space or enter key on the Today button selects today’s date and close the menu.



---

# index

---
title: Date and time selectors
tab_title: Code
description: Interactive calendar or time selector that allows users to choose a specific date or time.
meta_description: Get code for interactive calendar or time selectors that allow users to choose a specific date or time. 
thumbnail: assets/components/date-selector-graphic.svg
categories:
  - inputs
  - selection-controls
---

## Component Code Examples: date-and-time-selectors

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the date-and-time-selectors component
const component = parsed.components.find(c => c.name === 'date-and-time-selectors');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `date-and-time-selectors`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples


---

# usage

---
title: Date and time selectors
tab_title: Usage
tab_order: 1
description: Interactive calendar or time selector that allows users to choose a specific date or time.
meta_description: Learn how to use interactive calendar or time selectors that allow users to choose a specific date or time. 
thumbnail: assets/components/date-selector-graphic.svg
keywords: ["Date picker", "time picker", "calendar selector", "calendar picker", "date input", "time input"]
related:
  components:
    - input
  patterns:
    - forms
---

Date and time selectors allow users to input or select a single or range of dates and times from the past, present, or future. They often appear in [Forms](https://design.visa.com/patterns/forms) to condense space and provide a clear, concise selection process. Date and time formats are usually determined by the application and localization standards.
<br />
By default, the date and time selector menu will display the current date, time, or the most applicable month, year and time.
<br />
Also known as: Date picker, time picker, calendar selector, calendar picker, date input, time input.

## Anatomy

<img src="https://design.visa.com/assets/components/date-time-selector/date-selector-anatomy.svg" alt="Date selector with menu expanded"/>
**A. Input (required):** Text field enabling users to enter custom date text.<br/>
**B. Calendar icon button (required for web):** UI icon button that indicates and expands/collapses the calendar menu.<br/>
**C. Native date selector menu (required for web):** Container displaying the dates in a calendar format.<br/> 
**D. Month and year label (required):** Text communicating the month and year represented in the calendar.<br/>
**E. Month navigation arrows (required):** UI icon buttons for navigating to past and future months within the same year.<br/>
**F. Week day labels (required):** Abbreviated labels indicating the days of the week from Sunday to Saturday.<br/>
**G. Current date (required):** Outlined square or other indicator communicating the current date based on the user’s settings.<br/>
**H. Selected date (required upon selection):** Filled square or other indicator highlighting the date the user selected.<br/>
**I. Clear button (required):** UI icon button that clears the selected date and closes the date selector menu.<br/>
**J. Today button (required):** Text button that resets the calendar to select today’s date.<br/>
**K. Confirm button (required in mobile only):** Confirms the user’s date selection and closes the date selector menu.

## Usage

When to use and when not to use different types of date and time selectors

- Type: For viewing the date in context of the days of the week.
- When to use: If the dates are years in the past and would require more effort to navigate back than to input the date.

- Type: For selecting a custom period of time from one date to another.
- When to use: For selecting two unrelated dates.

- Type: If the time input is limited to what is provided in the dropdown.
- When to use: If time is not limited to what's provided in the dropdown or users may prefer to enter a custom time.

## Best practices
- Follow the default appearance and behavior of date and time selectors on different browsers.
- Always consider local and regional preferences for date and time formats.
- Follow all guidelines for using text fields in [Input](https://design.visa.com/components/input/usage).

### Default date selector
Date selectors help users choose a date from a calendar view. They're typically used for tasks like scheduling, when users would benefit from understanding the relationship between a date and the day of the week.

<img src="https://design.visa.com/assets/components/date-time-selector/input-bp-show-hide.svg" alt="Date selector with calendar menu expanded"/>
- Only display dates up to a year in the past or present from the current date to avoid overwhelming users.
- Use a simple date input for memorable, familiar, or dates that do not require the user to reference a calendar to recall.
- Always provide users with the option to enter the date in addition to selecting the date within the menu or modal.

### Date range selector
Date range selectors help users in choose a date span while providing the day of the week context. They’re typically used for selecting precise or significant date ranges, when users would benefit from understanding the relationship between a date and the day of the week.

<img src="https://design.visa.com/assets/components/date-time-selector/date-range-selector.svg" alt="Date selector for a start date placed left of an expanded date selector for an end date"/>
- Place the input fields next to each other for screens with enough horizontal space.
- Stack date selectors with the start date on top for screens with limited horizontal space.
- Always provide users with the option to enter the date in addition to selecting the date within the menu or modal.

### Time selector
Time selectors help users select times from a dropdown list when options may be limited by availability. Typically, the system will automatically adopt a 12- or 24-hour clock based on the device settings. The default time will be highlighted in blue, however only one column (hours, minutes, am/pm) can be in focus at a time.

<img src="https://design.visa.com/assets/components/date-time-selector/time-selector-behaviors.svg" alt="12-hour clock time selector placed left of a 24-hour clock time selector"/>
- Allow users to change between 12- and 24-hour clock for time inputs.

### Credit card expiration date
Separate select fields for month and year are commonly utilized for credit card expiration date inputs. This lockup is especially beneficial for products catering to international users to ensure the date is entered correctly, as the order can vary by region.

<img src="https://design.visa.com/assets/components/date-time-selector/date-selector-behaviors-input-1.svg" alt="Credit card expiration date input"/>
- Clearly label each select field to specify if selecting the month or year, preventing any confusion.
- Always list all 12 months in the dropdown menu, formatted as MM.
- Present the current year along with the following 19 years, for a total of 20 years in the dropdown menu, formatted as YY.
- Enable users to type to quickly navigate to their desired option and select it without needing to open the dropdown menu.
- Refer to [Select (native)](https://design.visa.com/components/select/usage) and [Card input](https://design.visa.com/patterns/card-input) guidelines for further guidance on implementing this lockup.

### Optional vs. required labels
Always ensure required fields are clearly labeled. While this may seem repetitive, it helps users scan for necessary information and reduces errors. There are two methods for labeling required fields based on your use case. Whichever method you select, use it consistently across your experiences. <br/><br/>
**Note:** Previous VPDS guidance recommended only marking optional fields. Our guidance has been updated to reflect current [Nielsen Norman Group](https://www.nngroup.com/articles/required-fields/)<!-- aria-label="Nielsen Norman Group (opens in a new tab)" --> recommendations. Learn more about optional vs. required labels in [Forms](https://design.visa.com/patterns/forms/#optional-vs-required-labels).

                    
              ### “Required” in the label (preferred method)
              
              <Typography variant="body-2">Including “required” within the label ensures it’s easy to find, particularly when instructions at the top might not be visible while scrolling. This method bolsters accessibility for both sighted and non-sighted users. </Typography>  
              
                <img src="https://design.visa.com/assets/components/date-time-selector/input-bp-required.svg" alt="Collapsed date selector with 'required' in the label"/>
              
              - Mark all fields that are required. This ensures you’re as explicit and transparent as possible.
              - Include “(required)” in field label with a space between the last word and the first parenthesis. 
                 
          
                    
              ### Asterisk in the label (alternative method)
              <Typography variant="body-2">
              Asterisks are commonly used to indicate required fields. The main advantage to using this method is that it doesn’t take up much space, helps users along a common edge, and can be used in addition to formatting hints in the label. 
              </Typography>
              
              <img src="https://design.visa.com/assets/components/date-time-selector/input-bp-asterisk.svg" alt="Collapsed date selector with asterisk in the label and a legend above noting that the asterisk indicates a required field"/>
              
                - Always include a legend or key at the top of the content area noting that the asterisk indicates a required field.
                - Place the asterisk at the beginning of the label with a space between the symbol and the first word.
          
    

### When required is implied
Although it's usually recommended to label required fields, there are cases where it’s implied that the field is required. This is common when there’s a one or two fields fundamental to completing of a task, like the username and password fields on a login screen. In these cases, marking the fields required isn’t necessary but can add additional clarity.

### Labeling optional fields
It’s not generally necessary to mark which fields are optional. While doing so can support clarity, it also adds unnecessary visual noise. Whatever you choose, apply the choice consistently to avoid confusion.

## Behaviors

### Input and menu functionality
Date and time selectors include both an input field and interactive menu, allowing users to type custom text or select from the menu directly. On page load, the menus remain closed until prompted by the calendar or clock UI icon button.
<br />
When the user expands the date selector menu, it shows the current month and year with the current date in focus, but not selected. When the user expands the time selector menu, it shows the default or first available time in focus, but not selected.
<br />
**Note:** The examples below demonstrate this behavior using the default date selector, but the same functionality applies to the date range selector and time selector.

#### Input functionality

When the menu is collapsed, users can enter a custom date or time by typing in the input field. If users expand the menu after entering custom input, the date or time appears selected in the menu.

<img src="https://design.visa.com/assets/components/date-time-selector/date-selector-behaviors-selection-typed.svg" alt="A date selector menu is expanded to show the selected date matches the date entered in the input field"/>
- Clearly indicate the required format for the date or time entry in the input field label.

#### Menu functionality

When the menu is expanded, users can select a date or time by interacting directly with the menu. Once a date or time is selected, it’s shown in the input field and the menu automatically collapses. If users select the “Today” button, it will automatically select the current date and collapse the menu.

<img src="https://design.visa.com/assets/components/date-time-selector/date-selector-behaviors-selection-manual.svg" alt="A date selector menu is expanded to select a date that is shown in the input field after the menu collapses"/>
- Ensure the selected date is reflected automatically in the input field.

#### Changing the month and year

To change the month or year, the user selects the month and year label at the top of the calendar. This switches the view from the calendar to a list of years. When the user selects a year, it expands like an accordion to reveal the 12 months within that year. Once they select a month, the menu switches back to the calendar view.

<img src="https://design.visa.com/assets/components/date-time-selector/input-bp-show-hide-1.svg" alt="A date selector menu is expanded to show a list of years and a list of all the months to select in 2024"/>

### Date range limits
Since date range selectors require users to select a start and end date, the selection order impacts what dates are available for selection. This ensures the start date is never later than the end date, and vice versa.

            
      #### Start date selected first

        When a start date is chosen first, it limits the options available for the end date. When the user prompts the end date menu, any dates that come before the chosen start date appear disabled. This ensures the end date can never be earlier than the start date. 
              
      <img src="https://design.visa.com/assets/components/date-time-selector/date-selector-behaviors-selection-typed-1.svg" alt="Expanded date selector for end date with dates before chosen start date disabled"/>
        - Ensure only one menu is open at a time by collapsing the menu as soon as soon as a selection is made.     
  
            
      #### End date selected first

        When an end date is chosen first, it limits the options available for the start date. When the user prompts the start date menu, any dates that come after the chosen end date appear disabled. This ensures the start date can never be later than the end date.
              
      <img src="https://design.visa.com/assets/components/date-time-selector/date-selector-behaviors-selection-typed-2.svg" alt="Expanded date selector for start date with dates after chosen end date disabled"/>
        - Ensure only one menu is open at a time by collapsing the menu as soon as soon as a selection is made.      
  
 

 ### Docked menu placement
 As a docked menu, the date selector is attached or 'docked' to the input field. This means its position is directly related to the input field. The menu has a fixed width and doesn't scale with the input field or screen size. The input field length can vary and may not match the menu's width.

 <img src="https://design.visa.com/assets/components/date-time-selector/input-bp-show-hide-2.svg" alt="Two expanded date selectors with different input field widths but fixed menu widths"/>
 - Ensure the menu is left-aligned for left to right reading languages, and right-aligned for right to left reading languages.

## Content
- Always use sentence case except for proper nouns or acronyms.
- Use plain language and avoid abbreviations or jargon.
- Reference [Content](https://design.visa.com/content) for additional guidance on crafting content within apps and experiences. 
- Avoid using unnecessary articles like “the” or “an”, unless they’re included in the proper name of a product or service.

### Labels

- Limit field labels to three to five words when possible.
- Use parallel structure across field labels, using either nouns like "Date" or verbs like "Select a date". Learn more about parallel structure in [Grammar and punctuation](https://design.visa.com/content/grammar).

### Inline message

- Be brief, descriptive, and helpful, limiting the message to one to two short sentences.
- Use sentence case and punctuation. The only exceptions are proper nouns or names. 
- Give additional guidance about the field and how to use it if necessary.
- Provide useful information including why a field is needed (if not obvious) without being technical.
- Give an example or specific syntax or values for inputs to help avoid errors.

#### Inline error message

- Follow the general rules for inline messages such as limiting the message to one to two sentences with punctuation.
- Draw attention, without causing frustration. Explain what happened and what they need to do to correct the error.
- Use prescriptive language to provide a clear guidance, actions, instructions, and answers, then get out of their way.
- Communicate whether the problem can occur again and offer an alternative backup solution in case it does.
- Clearly outline the simplest resolution (if applicable) without sending them to another location for answers.

## Platform considerations
Depending on the viewing device(s), the choice can be made to utilize either a web or mobile-based calendar element.

### Web
On web, the calendar typically appears as a docked menu, which is beneficial for leveraging larger screen sizes. However, it's usually not recommended for mobile interfaces. To learn more, reference [Mobile](https://design.visa.com/components/date-selector/usage/#mobile).

<img src="https://design.visa.com/assets/components/date-time-selector/date-selector-platform-docked.svg" alt="Date selector with menu expanded"/>

#### Appearance

Native date selectors are utilized due to their ready-made functionality and inherent accessibility features. However, it's important to note that the appearance of these menus can vary across different browsers and operating systems.

<img src="https://design.visa.com/assets/components/date-time-selector/date-selector_andriod-ios.svg" alt="Google Chrome and Safari native browser versions of date selector"/>

### Mobile
On mobile devices the menu appears as a modal.

- Always use OK and Cancel buttons within a mobile date and time selector.

## Development notes
Date input field help with the date formatting and with the validation of range. However, there are issues with **input type="date"** because of the limited browser support. In unsupported browsers, it will move to a simple **input type="text"**.


---

# accessibility

---
title: Dialog
description: Messages that float over page content and provide time-sensitive alerts.
meta_description: Find accessibility guidelines for messages that float over page content and provide time-sensitive alerts. 
thumbnail: assets/components/dialog-graphic.svg
tab_order: 2
---

## Best practices

<br />
**Note:** VPDS uses a native HTML dialog element and backdrop pseudo element. Our library components already handle some of the dialog behaviors.
- Ensure the screen reader announces the dialog title and/or content. When the dialog opens, focus is moved into it and is trapped there until it closes. Tabbing will cycle through the focusable elements in the dialog.
- Use an `h2` element for headings.
-  Place the close button at the end of the DOM in the dialog so that the keyboard navigation goes through all the content before the close button.
- Ensure the escape key closes the dialog. When a dialog closes, focus is returned to the control which triggered it. 

## Keyboard controls
### Keyboard focus tab order

Keyboard focus tab order for different types of dialog.

- Dialog: Standard keyboard focus tab order will follow the DOM order.

- Dialog: Focus should be placed on the first interactive element inside dialog, excluding close buttons.

- Dialog: Not recommended to use close buttons on dialogs that include form elements.

### Keyboard

Keyboard actions and their corresponding behaviors for dialog

- Key: Prompts the action associated with the focused interactive element in the dialog.

- Key: Moves keyboard focus to the next focused interactive element in the dialog.

- Key: Moves keyboard focus backwards to the previous interactive element in the dialog.

- Key: Closes the dialog.



---

# index

---
title: Dialog
tab_title: Code
description: Messages that float over page content and provide time-sensitive alerts.
meta_description: Get code for messages that float over page content and provide time-sensitive alerts. 
thumbnail: assets/components/dialog-graphic.svg
categories:
  - feedback-and-status
---

## Component Code Examples: dialog

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the dialog component
const component = parsed.components.find(c => c.name === 'dialog');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `dialog`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Dialog
tab_title: Usage
tab_order: 1
description: Messages that float over page content and provide time-sensitive alerts.
meta_description: Learn how to use messages that float over page content and provide time-sensitive alerts. 
keywords: ["Modal", "lightbox", "popup module", "alerts (iOS)", "alert", "dialog (Android)", "dialog feedback", "dialog box", "overlay"]
related:
  components:
    - banner
    - section-message
  patterns:
    - feedback-and-status
  content:
    - messaging
---

Dialogs are container that appears over a user’s workflow and provides time-sensitive messages. They can be used to communicate critical status alerts or situations, confirm an action, and facilitate quick user actions.
<br />
Also known as: Modal, lightbox, popup module, alerts (iOS), alert, dialog (Android), dialog feedback, dialog box, overlay.

## Anatomy

<img src="https://design.visa.com/assets/components/dialog/dialog-anatomy.svg" alt="Default dialog with callout A indicating the required title, callout B indicating the required message, callout C indicating the optional close button, callout D indicating the optional buttons, and callout E indicating the required overlay."/>

**A. Title (required):** Brief text summarizing the purpose of the dialog. <br/> **B. Message (required):** Descriptive text, or in some cases limited interactive elements, tables, or graphics. <br/> **C. Close button (optional):** Icon button that can be used in place of, but not with, a text button to dismiss the dialog. <br/> **D. Buttons (optional):** Primary and secondary text buttons used to prompt an action. <br/> **E. Overlay (required):** Shaded overlay communicating to the user that only the dialog is interactive.

## Usage

When to use and when not to use different types of dialogs

- Component: For informational messages that are of high enough priority to disrupt the user's workflow, even though they may not require immediate action.
- When to use: For low-priority, system-level messages. Use a [Banner](https://design.visa.com/components/banner/usage) instead. <br/><br/> For low-priority messages that don’t require user action or attention. Use a [Flag](https://design.visa.com/components/flag/usage) instead.

- Component: Success dialogs are not a common use case as they are too disruptive for low-priority confirmations.
- When to use: For system- or section-level success, messages including on-page event confirmations. Use a [Flag](https://design.visa.com/components/flag/usage) instead. <br/><br/> If the user is taken to a success page on submit. Don’t use a messaging component in this case.

- Component: For medium-priority messages that are of high enough priority to disrupt the user's workflow to warn of potential issues that may require action immediately or in the near future.
- When to use: For medium-priority, system-level  messages that require attention but not disruption. Use a [Banner](https://design.visa.com/components/banner/usage) instead. <br/><br/> For warnings contextually relevant to a section of a page or workflow. Use a [Section message](https://design.visa.com/components/section-message/usage) instead. <br/><br/> For low-priority warnings that don't require user action or attention. Use a [Flag](https://design.visa.com/components/flag/usage) instead.

- Component: For high-priority alerts communicating that critical errors or issues have occurred when completing a task or operation and must be fixed before continuing.
- When to use: For high priority, system-level errors that require attention, instead use a [Banner](https://design.visa.com/components/banner/usage). <br/><br/> For high-priority errors contextually relevant to a section of a page or workflow. Use a [Section message](https://design.visa.com/components/section-message/usage) instead.

- Component: For new features or systems to guide, introduce and explain the functionality of different elements to the users.
- When to use: For simple intuitive applications. <br/><br/> For experienced users that are familiar with the features or application. <br/><br/> For minor changes that could cause frustration.

## Best practices

  - Use dialogs sparingly and design them for efficient task completion, allowing users to return seamlessly to their workflow.<br/>
  - If the dialog is prompted by an action, return the focus to where the user was in their workflow.<br/>
  - Left-align buttons except for touring tips and mobile dialogs with full-width buttons. Learn about alignment in [Button](https://design.visa.com/components/button/usage).<br/>
  - Visit [Feedback and status](https://design.visa.com/patterns/feedback-and-status) to learn how to use messaging components, understand their level of disruption, and choose the appropriate messaging component for your context.

## Behaviors

### Dismissal

In general, users should be allowed to dismiss dialogs using a close icon button or text button. Dialogs should also dismiss when users complete an associated action, such as correcting an error. Avoid using timed auto-dismissal for dialogs, as they may disappear before screen readers finish announcing the text.

### Dialog height

While there are no strict minimum or maximum height requirements for dialogs, it’s essential to make adjustments based on factors such as use case, screen size, and content volume. As previously mentioned, avoid using full-page dialogs.

<img src="https://design.visa.com/assets/components/dialog/dialog-behaviors-height.svg" alt="Dialog height adjusting to the use case, screen size and content volume."/>

  - Adjust dialog height according to the use case, screen size, and content volume. Aim for clear, digestible information.<br/>
  - Be aware of the space above and below the dialog when setting size. Good spacing improves readability.<br/>
  - For extensive content use a scroll bar, but do so sparingly. If using, always ensure the title and buttons are visible. 

### Animation

Dialogs may animate. Typically, they fade in with the background overlay and fade out upon dismissal. 

<img src="https://design.visa.com/assets/components/dialog/dialog-behaviors-animation.svg" alt=""/>

  - Ensure animations are brief, subtle, and unobtrusive.<br/>
  - Implement animations consistently across flags in your experience, either animating all or none.

## Content

  - Learn how to craft content for messaging components, like dialogs, visit [Messaging](https://design.visa.com/content/messaging). <br/>
  - Follow guidelines for [Link](https://design.visa.com/components/link/usage) and [Button](https://design.visa.com/components/button/usage) components when labeling actions and destinations within dialog. 

## Platform considerations

### Mobile

<img src="https://design.visa.com/assets/components/dialog/dialog-platform-mobile.svg" alt="Mobile version of a dialog"/>

  - Position dialogs in the center of the page, ensuring left and right margins are 16 dp. <br/>
  - Configure buttons to fill the container if necessary to enhance visibility where screen space is limited. <br/>
  - Use a text button as the default close mechanism for mobile instead of the close icon button in the top right corner. <br/>
  - Use a close icon button as a close mechanism only if the calls to action are required for other actions.


---

# accessibility

---
title: Divider
description: Visual elements used to separate and group information on a page.
meta_description: Find accessibility guidelines for visual elements used to separate and group information on a page.
thumbnail: assets/components/divider-graphic.svg
tab_order: 2
---

## Best practices
 
  - Use the `<hr />` tag  for dividers used on web.
  - Use `aria-hidden=&quot;true&quot;` for decorative dividers to hide the element from the accessibility API. Reference [the coded examples](https://design.visa.com/components/divider)<!-- aria-label="divider code examples" -->.


---

# index

---
title: Divider
tab_title: Code
description: Visual elements used to separate and group information on a page.
meta_description: Get code for visual elements used to separate and group information on a page.
thumbnail: assets/components/divider-graphic.svg
categories:
  - structure-and-layout
---

## Component Code Examples: divider

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the divider component
const component = parsed.components.find(c => c.name === 'divider');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `divider`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Divider
description: Visual elements used to separate and group information on a page.
meta_description: Learn how to use visual elements used to separate and group information on a page.
keywords: ["Horizontal rule", "rule", "line"]
related:
  patterns:
    - forms
    - application-layouts
tab_order: 1
---

  Divider is a minimalistic visual component used for structuring and grouping information on a page. It subtly delineates different sections without causing distraction, thus enhancing user comprehension.
  <br />
  Also known as: Horizontal rule, rule,	line.

## Anatomy

  <img src="https://design.visa.com/assets/components/divider/divider-anatomy.svg" alt="A default divider with callout A, a section divider with callout B and a decorative divider with callout C."/>
  <Typography variant="body-2">
  **A. Default divider:** A medium-weight, neutral-colored horizontal line. <br/>
  **B: Section divider:** A heavy-weight, colored horizontal line. <br/>
  **C: Decorative divider:** A light-weight, neutral-colored horizontal line. <br/>
  </Typography>

## Usage

  When to use and when not to use different types of dividers

- Component: To clearly distinguish between sub-sections or groups of content within a section of page. <br/> <br/>
            In text-heavy contexts where it can improve readability by breaking up large blocks of text.
- When to use: When content grouping can be implied using white space.

- Component: To separate two distinct sections at the page level.
- When to use: In place of a default divider to separate content within a section.

- Component: As an aesthetic element to enhance the look or feel of your content.
- When to use: As a functional separator or when a divider is critical to understanding the organization of your content.

 
## Best practices

  - Use whitespace when possible to group content before resorting to using dividers. 
  - Use dividers where they make sense. They should help in grouping related content or separating unrelated content.
  - Keep the style of dividers consistent throughout your design to maintain visual harmony. 
  - Ensure decorative dividers meet accessibility contrast ratios. For more information, reference [Accessibility](https://design.visa.com/components/divider/accessibility).
  - Ensure margins are equal widths, whether you decide to implement full-width dividers or crop them to the margins.
 

  {/* DOS AND DONTS */}
  

### Divider hierarchy

    Divider styles are meant to communicate different types of content separation. The example below illustrates how you might combine divider styles to establish visual hierarchy. 

  <img src="https://design.visa.com/assets/components/divider/divider-hierarchy.svg" alt="A page mockup with default, section and decorative dividers used to separate sections in a form."/>


---

# accessibility

---
title: Dropdown menu
tab_order: 2
description: Interactive elements that allow users to select a single option from a list.
meta_description: Find accessibility guidelines for interactive elements that allow users to select a single option from a list.
thumbnail: assets/components/dropdown-menu-graphic.svg
---

## Best practices

<br/>
**Note:** Dropdown menu is a composite component.  Some of the following requirements are handled by the component out of the box. The contents of the menu are coded in a list comprised of buttons or links so screen readers announce the number of items in the menu.
- Ensure the button that opens the menu uses `aria-expanded`, which is true when the menu is open, and `aria-controls` with the `id` value of the menu container.
- Ensure the menu (which is a container with a list) uses `aria-hidden`, which is false when the menu is closed, and an `id` which is referenced by the triggering button.

## Keyboard controls
Dropdown menus are not coded as listboxes, unlike some similar components. Elements within the dropdown menu use their native roles and shouldn't have added role attributes.<br/><br/>

For menu items with actionable items (given the role of buttons in this case), Up/Down arrow keys are not applicable. When the menu is expanded, the user can navigate within the menu using Tab/Shift+Tab keys.

Keyboard actions and their corresponding behaviors for dropdown menu

- Key: Prompts button.

- Key: Moves to the next focusable element within the menu (unlike listbox). If focus is on the last item, tab closes the menu and moves to the next focusable element on the page.

- Key: Moves to the previous focusable element within the menu; if focus is on the first item, shift + tab moves to the triggering element.

- Key: Closes the menu.



---

# index

---
title: Dropdown menu
tab_title: Code
description: Interactive elements that allow users to select a single option from a list.
meta_description: Get code for interactive elements that allow users to select a single option from a list.
thumbnail: assets/components/dropdown-menu-graphic.svg
categories:
  - selection-controls
---

## Component Code Examples: dropdown-menu

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the dropdown-menu component
const component = parsed.components.find(c => c.name === 'dropdown-menu');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `dropdown-menu`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples


---

# usage

---
title: Dropdown menu
tab_title: Usage
tab_order: 1
description: Interactive elements that allow users to select a single option from a list.
meta_description: Learn how to use interactive elements that allow users to select a single option from a list.
keywords: ["Menu", "select menu", "command menu dropdown", "actions drop-down", "action menu", "picker (IOS)", "menu (Android)"]
related: 
  components: 
    - combobox
    - multiselect
---

Dropdown menus enable users to select an action from a list of options. They’re commonly used to save space by grouping related actions, or to provide actions in a confined space like a table column.<br/><br/>
Also known as: Menu, select menu, command menu dropdown, actions drop-down, action menu, picker (IOS), menu (Android).

## Anatomy
<img src="https://design.visa.com/assets/components/dropdown-menu/ddmenu-anatomy.svg" alt="An expanded dropdown menu with callout A indicating the required button, and a menu with callout B indicating the required menu item. A second expanded dropdown menu with callout C indicating the optional divider."/>
**A. Button (required):** Text or icon button used to open or close the dropdown menu.<br/>
**B. Menu option (required):** Individual option representing an action.<br/>
**C. Divider (optional):** Horizontal line used to group related actions.

## Usage
When to use and when not to use different types of dropdown menus

- Component: When there’s sufficient space to provide a list of actions with a label.
- When to use: As form input. Use [select](https://design.visa.com/components/select/usage) instead.

- Component: When space is limited and an icon can accurately summarize the options in the list.
- When to use: As form input. Use [select](https://design.visa.com/components/select/usage) instead.

## Best practices
- Group related actions together in the menu.
- Avoid using dropdown menus for critical actions that should be immediately available. 
- Ensure icon buttons are recognizable so users can anticipate what actions are included in the menu. 
- Include a scrollbar if menus are long and the container needs to have a maximum height.
- Avoid using a dropdown menu for navigation. If a dropdown menu needs to be used for navigation, follow guidance found in Link for “[Styling and coding buttons and links](https://design.visa.com/components/link/usage#styling-and-coding-buttons-and-links).”

### Buttons vs. links
Dropdown menus are intended to be used for actions only, but it rare cases, they may contain links. Always consult with accessibility partners to ensure interactions are accessible for all users.
<img src="https://design.visa.com/assets/components/dropdown-menu/ddmenu-bp-buttons-links.svg" alt="An expanded dropdown menu containing three items."/>
- Don’t mix buttons and links within a dropdown menu. 
- Follow all guidelines for labeling links to ensure it’s clear what they do and where they lead.

### Icon usage
Icons can be used in dropdown menus to make scanning easier and reinforce familiar ideas.
<img src="https://design.visa.com/assets/components/dropdown-menu/ddmenu-bp-icon-usage.svg" alt="An expanded dropdown menu containing items that each have an icon."/>
- Use icons consistently throughout the menu. For example, if you use icons for some options, use them for all. 
- Ensure icons are relevant and easy to understand to avoid unnecessary visual elements.

## Behaviors

### Destructive actions

Destructive actions refer to actions that delete or remove data. Dropdown menus can contain destructive actions as necessary. For more information, reference [Button](https://design.visa.com/components/button/usage) guidelines. 
<img src="https://design.visa.com/assets/components/dropdown-menu/ddmenu-behaviors-destructive.svg" alt="Two expanded dropdown menus, each featuring 'Delete' as one of the destructive menu items."/>  

### Placement
Menus can align to either side of the button based on its placement in the interface.
<img src="https://design.visa.com/assets/components/dropdown-menu/ddmenu-behaviors-placement.svg" alt="Two expanded dropdown menus, one is left-aligned and the other is right-aligned"/>

## Content
- Write all content in sentence case, except for acronyms or proper nouns, like the application name.
- Don’t use punctuation.
- Avoid abbreviations where possible.
- Limit labels to a few brief words to prevent unnecessary reflow. 
- Follow all additional guidance found in [Button](https://design.visa.com/components/button/usage) for crafting action labels. 
- Use parallel structure for menu option labels, either always starting with nouns or command verbs. Learn more about parallel structure in [Grammar and punctuation](https://design.visa.com/content/grammar).


---

# accessibility

---
title: Flag
description: Messages that provide low-priority updates about a process or event.
meta_description: Find accessibility guidelines for messages that provide low-priority updates about a process or event.
thumbnail: assets/components/flag-graphic.svg
tab_order: 2
---

## Best practices

<br />
**Note:** If you are using a screen reader on the code tab of this component, you may have heard multiple generic messages as examples load. These examples are used in the context of documentation to show the importance and usage of role or aria-live attributes which prompt the screen reader to read the component content aloud.
- Use `aria-live=&quot;&quot;` except for error messages which should use `aria-live=&quot;assertive&quot;`.
- Use `role=&quot;status&quot;` which is equivalent to `aria-live=&quot;polite&quot;` with `aria-atomic=&quot;true&quot;`.
- Ensure the type of flag (success, warning, etc.) is communicated verbally if it can’t be easily inferred from the message text.           

## Keyboard controls
Flags are comprised of other elements that use standard keyboard actions.
<br />
**Note:** Activating the Escape key does not close the flag, as that might disrupt what the user is doing by closing something else.

Keyboard actions and their corresponding behaviors for flags

- Key: Prompts the action associated with the focused interactive element.

- Key: Moves focus to the next focusable element.

- Key: Moves keyboard focus backwards to the previous interactive element in the banner.



---

# index

---
title: Flag
tab_title: Code
description: Messages that provide low-priority updates about a process or event.
meta_description: Get code for messages that provide low-priority updates about a process or event.
thumbnail: assets/components/flag-graphic.svg
categories:
  - feedback-and-status
---

## Component Code Examples: flag

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the flag component
const component = parsed.components.find(c => c.name === 'flag');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `flag`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Flag
description: Messages that provide low-priority updates about a process or event.
meta_description: Learn how to use messages that provide low-priority updates about a process or event.
keywords: ["Toast message", "snack bar", "notification", "banner"]
related:
  components:
    - banner
    - section-message
  patterns:
    - feedback-and-status
  content:
    - messaging
tab_order: 1
---

Flags provide contextual, low priority messages to the user. They’re primarily used for success messages or alerts that require minimal actions, if any, from the user.
<br />
Also known as: Toast message, snack bar, notification, banner.

## Anatomy

<img src="https://design.visa.com/assets/components/flag/flag-anatomy.svg" alt="A success flag with a required success icon indicated by callout A, an optional title indicated by callout B, a required message indicated by callout C, an optional close icon button indicated by callout D, and an optional action button indicated by callout E."/>

**A. Icon (required):** Visual indicator communicating the urgency of the flag. <br/> **B. Title (optional):** Brief text summarizing the purpose of the flag. <br/> **C. Message (required):** Descriptive message detailing important contextual information. <br/> **D. Close icon button (optional):** Icon button used as a close button alternative that allows users to manually dismiss the flag. <br/> **E. Button and link (optional):** Text button or link that prompts an action or directs users to relevant resources.

## Usage

When to use and when not to use different types of flags

- Component: For low-priority feedback or status updates that don’t require user action or attention.
- When to use: For neutral messages that are important enough to disrupt the users workflow but may not require action before continuing. Use a [Dialog](https://design.visa.com/components/dialog/usage) instead. <br/><br/> For low-priority, system-level messages. Use a [Banner](https://design.visa.com/components/banner/usage) instead. <br/><br/> For low-priority information contextually relevant to a section of a page or workflow. Use a [Section message](https://design.visa.com/components/section-message/usage) instead.

- Component: For system- or section-level success, including on-page event confirmations. This is the most frequent use case.
- When to use: If the user is taken to a success page on submit. Don’t use a messaging component in this case.

- Component: For low-priority warnings that don’t require user action or attention.
- When to use: For medium to high-priority warnings that must be fixed or acknowledged before continuing. Use a [Dialog](https://design.visa.com/components/dialog/usage) instead. <br/><br/> For medium-priority, system-level  messages that require attention but not disruption. Use a [Banner](https://design.visa.com/components/banner/usage) instead. <br/><br/> For medium- or high-priority warnings contextually relevant to a section of a page or workflow. Use a [Section message](https://design.visa.com/components/section-message/usage) instead.

- Component: Error flags are not a common use case.
- When to use: For high-priority errors that must be fixed before continuing. Use a [Dialog](https://design.visa.com/components/dialog/usage) instead. <br/><br/> For high priority, system-level errors that require attention. Use a [Banner](https://design.visa.com/components/banner/usage) instead. <br/><br/> For high-priority errors contextually relevant to a section of a page or workflow. Use a [Section message](https://design.visa.com/components/section-message/usage) instead.

## Best practices

- Limit the use of flags, as overusing can desensitize users and reduce the value.<br/>
- Visit [Button](https://design.visa.com/components/button/usage) to learn about best practices for alignment, order, and language for calls to action.<br/>
- Visit [Feedback and status](https://design.visa.com/patterns/feedback-and-status) to learn how to use messaging components, understand their level of disruption, and choose the appropriate messaging component for your context.

## Behaviors

### Dismissal

In general, users should be allowed to dismiss flags using a close icon button or text button. Flags should also dismiss when users navigate to a new page or complete an associated action, such as correcting an error. Avoid using timed auto-dismissal for flags, as they may disappear before screen readers finish announcing the text. 

### Animation

Flags may use animated graphics. They appear by sliding onto the screen from the nearest edge (top, bottom, left, or right).

<img src="https://design.visa.com/assets/components/flag/flag-behaviors-animation.svg" alt=""/>

- Ensure animations are brief, subtle, and unobtrusive.
- Implement animations consistently across flags in your experience, either animating all or none. 

## Content

- Learn how to craft content for messaging components, like flags, visit [Messaging](https://design.visa.com/content/messaging). <br/>
- Follow guidelines for [Link](https://design.visa.com/components/link/usage) and [Button](https://design.visa.com/components/button/usage) components when labeling actions and destinations within flags. 

## Platform considerations

### Mobile
Flags are available in both mobile and web and should be implemented similarly across both platforms.

- Extend mobile flags across the screen width to ensure they’re large enough to read.
- Place mobile flags consistently at the top or bottom of the screen without covering interactive elements.



---

# accessibility

---
title: Footer
description: Content fixed at the bottom of a page to provide important information or links.
meta_description: Find accessibility guidelines for content fixed at the bottom of a page to provide important information or links.
thumbnail: assets/components/footer-graphic.svg
tab_order: 2
---

## Best practices

- Ensure logos have accessible text using an `aria-label`. Add the label to the svg for custom logos.
- Use a class of `v-logo-hc-dark-foreground` or `v-logo-hc-light-foreground` to make sure logos always have sufficient contrast against the background in Windows high contrast mode.

## Keyboard controls

  Keyboard actions and their corresponding behaviors for footers

- Key: Activates link.



---

# index

---
title: Footer
tab_title: Code
description: Content fixed at the bottom of a page to provide important information or links.
meta_description: Get code for content fixed at the bottom of a page to provide important information or links.
thumbnail: assets/components/footer-graphic.svg
categories:
  - navigation
  - structure-and-layout
---

## Component Code Examples: footer

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the footer component
const component = parsed.components.find(c => c.name === 'footer');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `footer`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Footer
description: Content fixed at the bottom of a page to provide important information or links.
meta_description: Learn how to use content fixed at the bottom of a page to provide important information or links.
keywords: ["Bottom section", "end section", "UITabBar (iOS)", "BottomNavigationView (Android)"]
related:
  components:
    - vertical-navigation
  patterns:
    - application-layouts
tab_order: 1
---

Footers are persistent elements on web pages that provide quick links and legal content. Some applications might not include a footer on each page and can provide the same information from a navigation bar or Settings/About section. When they’re used, they’re placed at the bottom of the page.<br/><br/>
Also known as: Bottom section, end section, UITabBar (iOS), BottomNavigationView (Android).

## Anatomy
 
  <img src="https://design.visa.com/assets/components/footer/footer-anatomy.svg" alt="A footer with a required brandmark indicated by callout A, copyright text indicated by callout B, and optional links indicated by callout C."/>    

 
**A. Brand mark (required):** Visual element representing Visa, a partner brand, or a fictitious brand associated with the product.<br/>
**B. Copyright text (optional):** Text providing critical legal information including a copyright symbol, year of creation, the author’s name, and a rights statement.<br/>
**C. Links (optional):** Link components directing users to legal information.

## Usage

  When to use and when not to use different types of footers

- Component: When footer contains minimal content.
- When to use: As a source for site navigation.

- Component: When there’s a need for more content within the footer area including links to important site resources.
- When to use: As the main source for site navigation.

## Best practices

- Follow all guidance found in [Link](https://design.visa.com/components/link) when implementing links in the footer.
- Ensure the footer appears the same on every page where it’s used.

### Placement

Placement of the footer depends on the use case and experience needs. Consider the three options below when using the footer component.

#### Fixed

Footers can be fixed to the bottom of a web page to let users know they’ve reached the end. This is the default behavior for footers as its the least disruptive to the user.

<img src="https://design.visa.com/assets/components/footer/footer-fixed.svg" alt="A footer fixed to the bottom of a web layout."/>

#### Sticky

Footers can also be “sticky” to ensure they’re always visible. Sticky footers stay at the bottom of the viewport regardless of how the user scrolls.
  
<img src="https://design.visa.com/assets/components/footer/footer-sticky.svg" alt="A sticky footer that maintains its position on the bottom of the screen as the page is scrolled."/>
- Only use this method if the footer content is critical and needs to be accessible at all times.

#### About pages
  
The application can use an “About” page if the footer content doesn’t need to appear on every page. This page could include content like copyright notices or acknowledgments, providing a less high-profile way for users to access this information. Check with Product Legal requirements about what must be accessible to users at all times.

<img src="https://design.visa.com/assets/components/footer/footer-about-pages.svg" alt="An About page with links to learn about career opportunities and to email for more help or questions. A copyright notice is included at the bottom of the page."/>

## Platform considerations

### Web

On most web pages, the footer size is determined by the screen size. The footer component has responsive breakpoints to support a full range of devices. The standard 1440 px footer is recommended for desktop web environments.
<img src="https://design.visa.com/assets/components/footer/footer-platform-web.svg" alt="A web footer with a brandmark and copyright text on the left and three links on the right"/>
  

### Tablet

On tablets, the footer size and layout is determined by screen size and orientation. The standard approach for tablet footers is 768px.
<img src="https://design.visa.com/assets/components/footer/footer-platform-tablet.svg" alt="A tablet footer with a brandmark on top, three links below it, and copyright text on the bottom"/>

### Mobile

On mobile, the footer size and layout are determined by the screen size and orientation. The mobile navigational footer can be adjusted for different breakpoints to support a range of mobile devices, including tablets and smartphones. The standard approach is 768px for tablets, 767px to 346px for devices between tablet and mobile, and 345px for mobile devices.
<img src="https://design.visa.com/assets/components/footer/footer-platform-mobile.svg" alt="A mobile footer with a brandmark and copyright text on the top and three links on the bottom"/>

## Content
- Write all content in sentence case, except for acronyms or proper nouns, like the application name.
- Don’t use punctuation for navigation items.
- Ensure the links in navigation footers match page titles to enhance the user’s understanding of the site’s information hierarchy. 
- Ensure the copyright notice only contains the following details: copyright symbol, year of creation, name of author, rights statement.
- Follow guidance for labeling links. Learn more in [Link](https://design.visa.com/components/link).


---

# accessibility

---
title: Horizontal navigation
description: Menu placed at the top of a site that links to important pages or features.
meta_description: Find accessibility guidelines for horizontal navigation menus placed at the top of a site that links to important pages or features.
thumbnail: assets/components/horizontal-graphic.svg
tab_order: 2
---

## Best practices

<br/>
**Note:** Horizontal navs are made up of multiple components. Follow guidelines for each of those.
- Use a native HTML `header` landmark. Any `nav` landmark elements used within, such as for the mobile menu, need to have unique and descriptive `aria-labels`.
- Don’t use the word “navigation” in the `aria-label`, as this will be announced automatically and be redundant for screen readers.
- Use `aria-current=&quot;page&quot;` on the link which leads to the current page. Links in the vertical menu look like tabs and use CSS classes for tabs, but are not tabs and don’t have tab roles.
- Adjust the behaviors and breakpoints for horizontal navigation to fit your app.The horizontal nav should be responsive, so as the viewport gets narrower, content becomes hidden until the “hamburger” mobile menu is visible. 

### Logos
Our library has a classname just for the application name in the horizontal navigation component. There is a component for the Visa logo that adjusts for the user’s high contrast settings.
- Ensure the logo has an accessible name or is inside a link with an accessible name with `aria-hidden=&quot;true&quot;` on the svg.
- Use one of the library’s classes for high contrast with a custom logo. Choose between the class for light or dark foreground depending on the custom logo. Setting a contrasting background behind the brand logo ensures it will have maximum contrast in high contrast mode without a visible change in default contrast mode.

### Skip to main content link

The skip to main content link allows keyboard users to go directly to the main content of the page.  This link is first in the DOM (unless there is a skip to login link). It appears when users land on the page and activates the tab key and is only visible when it receives keyboard focus. Activating the link moves focus to the `main`component.
<br/>
Reference the [examples](https://design.visa.com/components/horizontal-navigation) to learn how to implement VPDS's skip-link styles.

### Skip to log in link
When navigation includes an account log in, the skip to log in link will appear when users press tab after page load and is tacked onto the top of the navigation bar. If user presses tab again, the user will be prompted with the skip to main content link.
<img src="https://design.visa.com/assets/components/nav-horizontal/vertnav-accessibility-visual.svg" alt="Horizontal navigation with a skip to login link"/>

## Keyboard controls
Keyboard actions and their corresponding behaviors for horizontal navigation

- Key: Activates the focused element.

- Key: Moves keyboard focus forwards to the next interactive element.

- Key: Moves keyboard focus backwards to the previous interactive element.



---

# index

---
title: Horizontal navigation
tab_title: Code
description: Menu placed at the top of a site that links to important pages or features.
meta_description: Get code for horizontal navigation menus placed at the top of a site that links to important pages or features.
thumbnail: assets/components/horizontal-graphic.svg
categories:
  - navigation
  - structure-and-layout
---

## Component Code Examples: horizontal-navigation

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the horizontal-navigation component
const component = parsed.components.find(c => c.name === 'horizontal-navigation');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `horizontal-navigation`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Horizontal navigation
description: Menu placed at the top of a site that links to important pages or features.
meta_description: Learn how to use horizontal navigation menus placed at the top of a site that links to important pages or features.
keywords: ["Horizontal menu", "horizontal navigation bar", "top navigation bar", "horizontal tab navigation", "row navigation", "UITabBarController (iOS)", "TabLayout (Android)"]
related:
  components:
    - vertical-navigation
    - top-app-bar
  content:
    - information-architecture
tab_order: 1
---

The horizontal navigation component is a container enabling users to navigate a product or experience. It's a common type of menu that's usually placed at the top of a website.
<br/>
Also known as: Horizontal menu, horizontal navigation bar, top navigation bar, horizontal tab navigation, row navigation, UITabBarController (iOS), TabLayout (Android).

{/* ANATOMY */}

## Anatomy

<img src="https://design.visa.com/assets/components/nav-horizontal/navigation-horizontal-anatomy.svg" alt="Horizontal navigation that has brandmark indicated by callout A, application name indicated by callout B, link label indicated by callout C, global search indicated by callout D, notification icon indicated by callout E, notification badge indicated by callout F, user profile with chevron icon indicated by callouts G and H."/>

**A. Brand mark (optional):** Visual element representing Visa, a partner brand, or a fictitious brand associated with the product. <br/> **B. Application name (optional):** Label indicating the name of the application. <br/> **C. Navigation link (required):** Label indicating the destination of the link. <br/> **D. Nav menu (optional):** Menu that expands to show nested navigation items under a common heading or category. <br/> **E. Global search (optional):** Icon button prompting a global search bar to find content across the whole site or app. <br/> **F. Notification badge (optional):** Badge component that expands and collapses the notification tray. <br/> **G. User profile (optional):**  Avatar component representing the current user’s account.

{/* USAGE */}

## Usage

  When to use and when not to use different types of horizontal navigation components

- Component: For websites with a few main navigation items.
- When to use: If navigation items are lengthy or complex.

- Component: For websites with more navigation items that require extra space.
- When to use: If website navigation is limited and simple.

     
{/* BEST PRACTICES */}

## Best practices
- Reference [Application layouts](https://design.visa.com/patterns/application-layouts) for help deciding which navigation component is best for your use case.
- Ensure the order of the navigation items is consistent throughout the application so users aren’t confused.
- Avoid exceeding seven items or links in the main navigation.
- Consider making the brand mark and/or application name function as a link to the homepage of the experience.
- Ensure the navigation bar remains visible as the user scrolls. 
- Follow all guidance found in [Search](https://design.visa.com/patterns/search), [Notification tray](https://design.visa.com/patterns/notification-tray), [Link](https://design.visa.com/components/link/usage), and [Avatar](https://design.visa.com/components/avatar/usage) when implementing those items in the navigation. 

### Default horizontal navigation

The default horizontal navigation bar includes a single level of navigation items. Items can link directly to a page, dropdown to show nested items, or prompt related functions like a search bar or notification tray. 
<img src="https://design.visa.com/assets/components/nav-horizontal/nav-horizontal-bp-menu.svg" alt="A default horizontal navigation menu."/>

### Stacked horizontal navigation
The stacked navigation bar provides extra space for websites with more navigation items. If the default bar looks crowded in your app, the stacked version can help declutter the experience. The first level should contain navigation icons and functions such as user profile, search and notification, while the second level should contain page links.

<img src="https://design.visa.com/assets/components/nav-horizontal/nav-horizontal-bp-stacked-variation.svg" alt="Stacked horizontal navigation component"/>

### Nav menus

Nav menus refer to dropdowns in the navigation bar that expand to show nested links. The top-level label doesn’t link to a specific page, and doesn’t change to reflect the user’s selection.
<br/>
**Note:** Nav menus are built using a modified dropdown menu component. For accessibility reasons, don’t use the default dropdown menu or replace it with a select component. Always consult with accessibility partners before modifying the behavior of any component.

### Icon usage
Icons can be used in navigation menus to make scanning easier and reinforce familiar ideas. 

<img src="https://design.visa.com/assets/components/nav-horizontal/nav-horizontal-bp-icon-usage.svg" alt="Horizontal navigation with leading icon text links"/>

- Ensure icon usage applies to all navigation items within the same hierarchy level. For example, if you use icons for some L1 labels, they should be used in all L1 items. 
- Omit icons for nested items, but if they’re necessary, ensure all items within the nested level has one.

{/* BEHAVIORS */}

## Behaviors

### Chevron direction
Visually differentiate expanded and collapsed sections using the chevron direction.  

#### Collapsed
Collapsed sections should use the downwards-pointing chevron to indicate collapsed content can be expanded.
<img src="https://design.visa.com/assets/components/nav-horizontal/nav-hor-chevron-collapse.svg" alt="Collapsed navigation tabs with a downward pointing chevron."/>

#### Expanded
Expanded sections should use the upwards-pointing chevron to indicate expanded content can be collapsed.
<img src="https://design.visa.com/assets/components/nav-horizontal/nav-hor-chevron-expand.svg" alt="Expanded navigation tabs with an upward pointing chevron."/>

## Platform considerations

### Web
Horizontal navigation is responsive for web applications, and the behavior is modified based on screen size. For tablet and smaller web screens, horizontal navigation reduces to the 768px component. At this size, links are placed in a hamburger menu and the application name and brand mark are centered instead of left-aligned.

<img src="https://design.visa.com/assets/components/nav-horizontal/nav-horizontal-platform-medium.svg" alt="Horizontal navigation for a medium-sized platform"/>

### Mobile
For mobile screens, the horizontal navigation bar turns into a [top app bar](https://design.visa.com/components/top-app-bar/usage) component instead, with the brand mark centered.

<img src="https://design.visa.com/assets/components/nav-horizontal/nav-horizontal-platform-small.svg" alt="Horizontal navigation for a small platform"/>

## Content
- Write all content in sentence case, except for acronyms or proper nouns, like the application name.
- Don’t use punctuation for navigation items.
- Ensure labels match page titles to enhance the user’s understanding of the site’s information hierarchy. 
- Limit labels to a few brief words to prevent unnecessary reflow. 
- Reference [Grammar and punctuation](https://design.visa.com/content/grammar) to learn how to use parallel structure for consistent phrasing.


---

# accessibility

---
title: Icons and illustrations
description: Explore Visa-branded and generic icon libraries that represent core functions, ideas, and content.
meta_description: Find accessibility guidelines for Visa-branded and generic icon libraries that represent core functions, ideas, and content.
thumbnail: assets/components/icons/icons.svg
tab_title: Accessibility
tab_order: 3
---

## Best practices

### Icons
**Note:** Nova icons include `aria-hidden=&quot;true&quot;` by default, which hides them from screen readers.
- Use an `aria-label` along with `aria-hidden=&quot;false&quot;` attributes on the svg when needed to give it an accessible name for a screen reader.
- Ensure icon buttons have an `aria-label`, although the icon it contains should not to avoid duplicate announcements.
- Edit the SVG code and add appropriate attributes to hard-coded custom icons, as a hardcoded `fill` color won’t adjust in Windows high contrast mode. 

### Images
- Ensure images using an `img` element have an `alt=&quot;&quot;` attribute.
  - Ensure purely decorative images have an empty `alt` value so they’re ignored by screen readers.
  - Ensure images that add meaning have an `alt` value with a succinct description and a color contrast ratio of at least 3:1.
- Use extreme caution when placing images or background images behind text. Remember that the screen will shift responsively for different screen sizes which will reposition items.
- Perform manual testing when needed as automated testing generally won’t test contrast between an image and foreground text.

### Right to left languages
- Use VPDS’s rtl class for “back”, “forward”, “previous”, and “next” arrows for left-to-right languages. Also be aware of directional icons including chevrons, “opens in a new window”, or “maximize tiny”.
- Ensure images that are directional or show progress adjust for rtl languages, as VPDS doesn’t have an RTL class for images. 



---

# code

---
title: Icons and illustrations
description: Explore Visa-branded and generic icon libraries that represent core functions, ideas, and content.
meta_description: Get code for Visa-branded and generic icon libraries that represent core functions, ideas, and content.
tab_title: Code
tab_order: 1
---

## Component Code Examples: icon

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the icon component
const component = parsed.components.find(c => c.name === 'icon');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `icon`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# index

---
title: Icons and illustrations
description: Explore Visa-branded and generic icon libraries that represent core functions, ideas, and content.
thumbnail: assets/components/icons/icons.svg
tab_title: Icons library
page_size: "full-width"
show_table_of_contents: false
---

<IconLibraryPage client:load="react" />


---

# usage

---
title: Icons and illustrations
description: Explore Visa-branded and generic icon libraries that represent core functions, ideas, and content.
meta_description: Learn how to use Visa-branded and generic icon libraries that represent core functions, ideas, and content.
tab_title: Usage
tab_order: 2
---

Icons are visual representations of core ideas, functions, or content. The Visa Product Design System currently supports two sets of icons: Visa-branded and generic for all other uses.
<br/>
Creating on-brand illustrations and visuals is key to designing cohesive, familiar product experiences. Using our brand symbol as the foundation, we extended our iconic color ratio into a unique icon and illustration system. Our new system is consistent and cohesive across our icons, enriched icons, and illustrations. The icons and enriched icons can scale into our illustration style to tell a more comprehensive story. These visual elements broaden our visual language to help us effectively communicate stories, actions, and ideas. 

## Anatomy

<img src="https://design.visa.com/assets/components/icons/icons-anatomy.svg" alt="Example icons of tiny resolution indicated by callout A, low resolution indicated by callout B, high resolution indicated by callout C, and an illustration indicated by callout D."/>

**A. Tiny resolution (16x16):** Simplified icons placed within components or areas with limited space. <br/> **B. Low resolution (24x24):** Icons with more detail placed within components when space permits. <br/> **C. High resolution (48x48):** Detailed icons placed outside components to add visual interest and meaning. <br/> **D. Illustration:** Larger visuals used to demonstrate complex ideas, add visual interest, or show processes.

## Icon best practices
- Use the Visa icon set for Visa-branded products and the generic set for fictitious or partner brands. Reference [Fictitious brands and user aliases (internal only)](https://bookmarks.visa.com/vpds-fictitious-brands) for more information.
- Use icons only when they add meaning, especially when used within interactive components.
- Avoid relying solely on icons to convey meaning unless they are universally understood by most users.
- Use the predefined or recommended icon sizes that correspond to each specific component design.

## Visa icons
The icon set for Visa-branded products is designed to mirror Visa's original brand assets as closely as possible. Any additions should follow brand guidelines. Existing icons and brand guidelines are available for review on [Visa Creative Asset Manager (VCAM)](https://bookmarks.visa.com/vpds-visa-creative-asset-manager-vcam). First-time users must contact Visa Brand & Marketing Governance or visit [Insite (internal only)](https://bookmarks.visa.com/vpds-insite-tools-brand)<!-- aria-label="Insite (opens in a new tab)" --> to set up an account.

<img src="https://design.visa.com/assets/components/icons/icons-visa.svg" alt="Visa icon set"/>
- Use single-color icons for most use cases. 
- Use two-color icons when appropriate for dark surfaces.

#### Design specifications

- Designed with a consistent 2px stroke width, suitable for all canvas sizes
- Incorporates open shapes to provide a unique and distinctive style
- Uses a corner radius that’s typically set at zero, although it may be adjusted depending on specific requirements
- Visit the [Visa brand guidelines](https://bookmarks.visa.com/vpds-visa-brand-identity-guide)<!-- aria-label="Visa brand guidelines (opens in a new tab)" --> for more details on design specifications

## Generic icons
Generic icons should be used for mockups or any product that does not specifically represent the Visa brand. This icon set originated from Vault, the previous iteration of the design system before Nova.

<img src="https://design.visa.com/assets/components/icons/icons-visa-1.svg" alt="Generic icon set"/>
- Use single-color icons all generic use cases.

#### Design specifications

- Designed with a 2px stroke width for use on tiny and low-resolution canvas sizes
- High-res icons combine 2px stroke with 3px stroke width used for details 
- Uses closed shapes to create clear and distinct icons
- Uses a corner radius that’s set at 1px for tiny and low-resolution canvases, and 2px for high-resolution canvases

## Icon size
To provide flexibility,  each icon is designed in three different sizes within each set. Although all versions of an icon share the same basic design, additional details are incorporated as the canvas size increases to ensure they maintain clarity and visibility.

         
          ### Tiny resolution

            Tiny-resolution icons are the smallest and simplest. They’re designed on a 16px by 16px canvas. Tiny icons are referred to as “UI icons” in the [Visa Brand Identity Guide](https://bookmarks.visa.com/vpds-visa-brand-identity-guide). 
            <img src="https://design.visa.com/assets/components/icons/Frame-4822.svg" alt="A variety of components using tiny icons"/>
            - Many components within the design system use the tiny icon size. This includes tabs, navigation components, badges, and more.
      
         
          ### Low resolution

            Low-resolution icons have more detail. They’re designed on a 24px by 24px canvas. Low-resolution icons are referred to as “Icons” in the [Visa Brand Identity Guide](https://bookmarks.visa.com/vpds-visa-brand-identity-guide). 
          <img src="https://design.visa.com/assets/components/icons/Frame-4823.svg" alt="A variety of components using low-resolution icons"/>
          - When space permits, it's recommended to use the low-resolution icons, as they communicate the purpose more clearly when compared to smaller versions.      
      

         
          ### High resolution

            High-resolution icons include additional details to provide visual interest. They’re designed on a 48px by 48px canvas. High-resolution icons are referred to as “Enriched icons” in the [Visa Brand Identity Guide](https://bookmarks.visa.com/vpds-visa-brand-identity-guide). 
            <img src="https://design.visa.com/assets/components/icons/Frame-4822-1.svg" alt="A content card using a high-resolution icon"/>
            - Use on content cards or for other, non-component use cases where space allows and visual interest is needed.
      

## Illustration best practices
Product teams must reference Visa’s brand guidelines throughout the design and development process to make informed decisions. Brand offers documentation for illustration guidance in the Brand Identity Asset Library.  In the future, we may offer an extension of this guidance specific to user experiences. <br/><br/>

Refer to the [Visa Brand Identity Guide](https://bookmarks.visa.com/vpds-visa-brand-identity-guide) on Visa Creative Asset Manager (VCAM) to learn more. First-time users on <abbr style="text-decoration: none" title="Visa Creative Asset Manager">VCAM</abbr> must contact Visa Brand & Marketing Governance or visit [Insite (internal only)](https://bookmarks.visa.com/vpds-insite-access-vcam) to set up an account.


---

# index

---
title: Components
description: Get usage, specs, and accessibility guidance for the building blocks of our system.
meta_description: Discover our components that are the building blocks of VPDS. These reusable elements reduce repetitive work and enhance consistency across Visa products.
page_size: large
show_table_of_contents: false
---

<ComponentGrid />


---

# accessibility

---
title: Input
description: Text fields that enable users to enter free-form content.
meta_description: Find accessibility guidelines for text fields that enable users to enter free-form content.
thumbnail: assets/components/input-graphic.svg
tab_order: 2
---

## Best practices

<br/>
**Note:** VPDS treats a `textarea` element like an input. See the examples for “multiline” inputs.
- Ensure all inputs have an `id` and a label with a matching `for` attribute.
- Link additional text using `aria-describedby`.
- Always indicate required fields in the label text or with an asterisk per [usage guidelines](https://design.visa.com/components/input/usage#optional-vs-required-labels). Additionally, it may have a `required` attribute.

## Keyboard controls
Keyboard shortcuts commonly for editing text should be maintained unless uniquely specified.

### Moving cursor

Keyboard actions and their corresponding behaviors for moving cursor

- Key: Navigates and moves the cursor within the text field.

- Key: Moves cursor to the next word.

- Key: Moves cursor to the previous word.

- Key: Scrolls text area up or moves cursor to the start of the line (depends on app).

- Key: Scrolls text area down or moves cursor to the end of the line (depends on app).

- Key: Moves cursor to the end of the line.

- Key: Moves cursor to the start of the line.

### Cut, paste, & undo

  Keyboard actions and their corresponding behaviors for cut, paste, and undo

- Key: Cuts selected text.

- Key: Cuts selected text.

- Key: Copies selected text.

- Key: Copies selected text.

- Key: Pastes selected text.

- Key: Pastes selected text.

- Key: Un-does last text.

- Key: Re-does last text.

- Key: Re-does last text.

### Delete

  Keyboard actions and their corresponding behaviors for delete

- Key: Deletes forward to word break.

- Key: Delete back to word break.

### Selecting text

Keyboard actions and their corresponding behaviors for selecting text

- Key: Selects all text.

- Key: Extends selection one character to the right.

- Key: Extends selection one character to the left.

- Key: Extends selection down one line (in multi-line use case).

- Key: Extends selection up one line.

- Key: Extends selection to the beginning of the line.

- Key: Extends selection to the end of the line.

- Key: Extends selection to the next word break.

- Key: Extends selection to the previous word break.

- Key: Extends selection to below paragraph.

- Key: Extends selection to above paragraph.

- Key: Extends selection to the top of the text.

- Key: Extends selection to the bottom of the text.

### Navigation

  Keyboard actions and their corresponding behaviors for navigation

- Key: Moves to next input field.

- Key: Moves to previous input field.

### Other

  Keyboard actions and their corresponding behaviors for manual line break (in multi-line use case)

- Key: Adds manual line break (in multi-line use case).



---

# index

---
title: Input
tab_title: Code
thumbnail: assets/components/input-graphic.svg
description: Text fields that enable users to enter free-form content.
meta_description: Get code for text fields that enable users to enter free-form content. 
categories:
  - inputs
---

## Component Code Examples: input

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the input component
const component = parsed.components.find(c => c.name === 'input');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `input`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Input
description: Text fields that enable users to enter free-form content.
meta_description: Learn how to use text fields that enable users to enter free-form content.
keywords: ["Text field", "input field", "text input", "text box", "form field", "text area", "UITextField (iOS)", "EditText (Android)"]
related: 
  patterns:
    - search
    - forms
tab_order: 1
---

{/* INTRO */}
Input fields allow users to enter free-form text or data. They are commonly used across long and short forms but can also appear as standalone elements like search bars.<br/><br/>
Also known as: Text field, input field, text input, text box, form field, text area, UITextField (iOS), EditText (Android).

{/* ANATOMY */}

## Anatomy
 
  <img src="https://design.visa.com/assets/components/input/input-anatomy.svg" alt="An input field having a label with callout A indicating the required label, a text field with callout B indicating the input, and an icon button with callout C. Another input field with a leading icon in the text field with callout D and an inline message with callout E. Another input field with scrollable content with callout F indicating the vertical scroll. The last input field can be expanded with callout G indicating the corner drag, and it includes a character counter with callout H indicating the characters remaining."/> 

  **A. Label (required):** Text indicating the purpose of the field and if the information is required.<br />
  **B. Input (required):** Text field enabling users to enter the requested information or data.<br />
  **C. UI icon button (optional):** Button controls relevant to the field. Visit [Button](https://design.visa.com/components/button) to learn more.<br />
  **D. Leading icon (optional):** Non-actionable icon at the beginning of the field indicating the purpose.<br />
  **E. Inline message (optional):** Text communicating format requirements or relevant guidance.<br />
  **F. Vertical scroll (optional):** Bar allowing users to scroll through long, multi-line entries.<br />
  **G. Corner drag (optional):** Visual indicator communicating that the field may be expanded by dragging.<br />
  **H. Character counter (optional):** Fraction indicating the number of current and maximum allowed characters.

{/* USAGE */}

## Usage

  When to use and when not to use different types of inputs

- Component: If the expected entry is a single line of text.<br /><br />
          For unique information that can’t be predicted with preset options.<br /><br />
          For memorable data that can be entered faster in a free-form format.
- When to use: If the expected entry is more than one line, use multi-line instead.
For predetermined options, use select components, such as [Select (native)](https://design.visa.com/components/select) or [Combobox](https://design.visa.com/components/combobox).

- Component: For single-use passcodes for verification purposes
- When to use: For entries other than a one-time passcode.

- Component: If the expected entry is more than a single line and spans multiple lines.
- When to use: If the expected input is a single-line response, use default instead.

- Component: To indicate the expected entry is a unit of measurement or currency.
- When to use: In place of leading or trailing icons or inputs without a unit of measurement or currency.

- Component: For search where users can enter information and discover results.
- When to use: For fields that do not return search results.

{/* BEST PRACTICES */}

## Best practices
  - Ensure the length of the input field matches the expected entry length.
  - Order fields to match user expectations. For example, “First name” followed by “Last name”.
  - Learn more about using input fields in forms in [Forms](https://design.visa.com/patterns/forms).

{/* DO + DON'T */}

  {/* LEADING ICONS */}
  ### Leading icons

    Leading icons are placed at the beginning of an input field and are not interactive elements. They visually indicate the type of information required, such as a mail icon for an email field. 
    <img src="https://design.visa.com/assets/components/input/input-bp-leading-icons.svg" alt="A required input field labeled email with a leading icon in the text field"/> 
  - Use one leading icon per input field as multiple icons can confuse users.
  - Use icons that are universally understood and directly correlate to expected entry.
  - Use leading icons consistently across experiences to help users learn and predict behavior.

  {/* UI ICON BUTTONS */}
  ### UI icon buttons
    UI icon buttons are placed at the end of an input field and are visual representations of actions the user can take. 
  <img src="https://design.visa.com/assets/components/input/input-bp-ui-icons.svg" alt="A required input field labeled password with a trailing show/hide icon in the text field"/> 
  - Only use one UI icon button per input field to ensure users have a single, clear action. 
  - Always place UI icon buttons in the trailing position of an input field. 
  - Ensure icons clearly and intuitively indicate the action they represent. 

  
              
      #### Show/hide input value

        Show/hide is an optional feature that allows users to display or hide inputted data, such as passwords. The icon button shows the opposite of the current state of the input display.
      <img src="https://design.visa.com/assets/components/input/input-bp-show-hide.svg" alt="Two input fields labeled password, one with password hidden and one with the password shown"/> 
       - Use the show/hide feature wisely, especially for sensitive data. By default, passwords should be hidden.       
    
              
      #### Combobox

        Chevron down icon is a UI icon button that prompts an option menu. The icon shows the direction the menu will expand when selected. For more info, reference [Combobox](https://design.visa.com/components/combobox).       
      <img src="https://design.visa.com/assets/components/input/input-bp-combobox.svg" alt="An example of a required input field with a trailing chevron icon button in the text field"/>
       - Ensure the chevron points downwards when the menu is collapsed and upwards when the menu is expanded.
    
  

  
              
      #### Information icon button

        Information icon is a UI icon button that prompts an inline message with additional guidance when selected. For more information, reference [Card input](https://design.visa.com/patterns/card-input).
      <img src="https://design.visa.com/assets/components/input/input-bp-info-icon.svg" alt="An input field labeled security code with an information icon in the text field displaying additional inline guidance when selected"/> 
       - Ensure the icon is universally recognized as an information symbol, usually a lowercase 'i' in a circle.
    
              
      #### Date selector

        Calendar icon is a UI icon button that prompts a dropdown menu allowing users to select a date instead of typing. For more information, reference [Date selector](https://design.visa.com/components/date-selector). 
      <img src="https://design.visa.com/assets/components/input/input-bp-date-selector.svg" alt="An input field labeled date with a calendar icon button that prompts a dropdown menu to select a date"/> 
       - Always provide users with the option to enter the date in addition to selecting the date within the menu or modal.
    
  

{/* PREFIX AND SUFFIX USAGE */}
  ### Prefix and suffix usage
  Prefix and suffix components are input fields with fixed expected data formats. The prefix-suffix component type automatically formats input to matches the expected type. For example, inputs with a “$” only accept monetary values and can auto format to include decimal points or commas in certain regions. <br /><br />
  Follow regional expectations when formatting currencies and when considering which units of measurement to use. Learn more in [Grammar and punctuation](https://design.visa.com/content/grammar).
  - Only use a prefix or suffix for inputs that require specific formatting, but don’t over use them.
  - Use universally recognized currency symbols that are easy to understand and distinguish from the input value.
  - Autoformat as the user types, but always ensure validation aligns with expected prefix or suffix symbols or codes.

              
      #### Prefix

     Prefixes are commonly used to indicate currencies, such as “$” or “€” and international international phone codes.
      <img src="https://design.visa.com/assets/components/input/input-bp-prefix.svg" alt="An example of a required input field with dollar currency symbol ($) as prefix in the text field"/> 
       - Consider regional norms for currency formatting. This includes the placement of currency symbols (before or after the value) and use of decimal points or commas as thousands separators, which differ across countries.
    
              
      #### Suffix 

        Suffixes are commonly used to indicate the unit of measurement or data format expected in the field. 
      <img src="https://design.visa.com/assets/components/input/input-bp-suffix.svg" alt="An example of a required input field with percentage symbol as suffix in the text field"/> 
      
       - Adhere to regional conventions when it comes to measurement systems. For example, some countries use the metric system (kilometers, kilograms, liters), while others use the imperial system (miles, pounds, gallons).
        
    
  

  {/* HIDDEN LABELS */}
  ### Hidden labels

  Typically, input fields should always include a label. However, in certain contexts such as search fields, the purpose of an input field can be understood without a visible label. In these cases, remember to include the label within the code to support screen readers and speech input software.<br /><br />
  Generally, there are two methods used to provide context when labels are hidden. It's important to choose a method and apply it consistently across your experiences.    

              
      #### Text and icon buttons
    
      The most common method is positioning a button (text or icon) beside the input field to provide context.

      <img src="https://design.visa.com/assets/components/input/input-bp-text-icon.png" alt="An input field with a search button next to it"/> 

       - Use clear labels indicating the outcome for text buttons.
       - Use icons for icon buttons that are easy to recognize and understand. Visit [Button](https://design.visa.com/components/button) to learn more.
    
    

              
      #### Leading icons and placeholder text

        In some scenarios, using an icon and placeholder text ensures there are two visual indicators to provide context.

      <img src="https://design.visa.com/assets/components/input/input-bp-placeholder.svg" alt="An input field with a search icon and search text label within the input area"/> 

       - Use placeholder text as a temporary label in addition to the leading icon. 
       - Use icons that are easy to recognize and understand. 
          
    
  

 ### Optional vs. required labels
Always ensure required fields are clearly labeled. While this may seem repetitive, it helps users scan for necessary information and reduces errors. There are two methods for labeling required fields based on your use case. Whichever method you select, use it consistently across your experiences. <br/><br/>
**Note:** Previous VPDS guidance recommended only marking optional fields. Our guidance has been updated to reflect current [Nielsen Norman Group](https://www.nngroup.com/articles/required-fields/)<!-- aria-label="Nielsen Norman Group (opens in a new tab)" --> recommendations. Learn more about optional vs. required labels in [Forms](https://design.visa.com/patterns/forms/#optional-vs-required-labels).

                    
              ### “Required” in the label (preferred method)
              
              <Typography variant="body-2">Including “required” within the label ensures it’s easy to find, particularly when instructions at the top might not be visible while scrolling. This method bolsters accessibility for both sighted and non-sighted users. </Typography>  
              
                <img src="https://design.visa.com/assets/components/input/input-bp-required.svg" alt="An input field labeled Email (required)"/> 
              
              - Mark all fields that are required. This ensures you’re as explicit and transparent as possible.
              - Include “(required)” in field label with a space between the last word and the first parenthesis. 
                 
          
                    
              ### Asterisk in the label (alternative method)
              <Typography variant="body-2">
              Asterisks are commonly used to indicate required fields. The main advantage to using this method is that it doesn’t take up much space, helps users along a common edge, and can be used in addition to formatting hints in the label. 
              </Typography>
              
              <img src="https://design.visa.com/assets/components/input/input-bp-asterisk.svg" alt="A note that says *indicates a required field above an input field with an asterisk before the label"/> 
              
                - Always include a legend or key at the top of the content area noting that the asterisk indicates a required field.
                - Place the asterisk at the beginning of the label with a space between the symbol and the first word.
          
    

### When required is implied
Although it's usually recommended to label required fields, there are cases where it’s implied that the field is required. This is common when there’s a one or two fields fundamental to completing of a task, like the username and password fields on a login screen. In these cases, marking the fields required isn’t necessary but can add additional clarity.

### Labeling optional fields
It’s not generally necessary to mark which fields are optional. While doing so can support clarity, it also adds unnecessary visual noise. Whatever you choose, apply the choice consistently to avoid confusion.

{/* BEHAVIORS */}

## Behaviors
  Input fields have optional behaviors and features you may implement based on use case. Learn about these below. 

{/* AUTOCOMPLETE */}
### Autocomplete
  Autocomplete is a feature that predicts a user's input based on previous entries or a predefined list. As a user types within an autocomplete-enabled field, the system presents a dropdown of suggestions. Selecting a suggestion fills the entire input field with that choice. Autocomplete is often used in form fields such as name, email, and address, and can also be used in search fields. However, it's often more effective and user-friendly to use autosuggest in search fields.<br /><br />
  **Note:** Autocomplete is typically enabled in most browsers by default. However, this depends on user settings or how your browser is managed by your organization. The visual representation and functionality of autocomplete formats can vary depending on the browser. Different browsers handle autocomplete differently, from the way they store and suggest input data to the visual presentation of suggestions. The example below is a general representation of the functionality.
     
      <img src="https://design.visa.com/assets/components/input/input-behaviors-autocomplete.svg" alt="An input field labeled First name (required), filled with the name Alex and an input field partially filled with a last name"/> 

  - Disable autocomplete for fields that contain sensitive information, like credit card numbers or one-time passcodes.
  - Consider styling limitations, for example the autocomplete dropdown provided by browsers has limited styling options.
  - Test autocomplete-enabled fields in various browsers to to ensure it works consistently and effectively across browsers.

{/* AUTOSUGGEST */}
### Autosuggest
  Autosuggest, like autocomplete, suggests options based on user input. However, it generates suggestions dynamically from a database or possible inputs, not just past entries. Autosuggest is commonly used in search fields for suggesting search terms or products. Remember, different applications handle autosuggest differently, from suggestion generation and presentation to dropdown menu interaction.<br /><br />
  **Note:** Implementing autosuggest requires significant development effort compared to native autocomplete. Its effectiveness relies on having relevant, quickly retrievable data. Components do not include search functionality by default. If search-like behavior is needed, this must be considered and implemented separately, which may require significant and additional development effort or potentially re-architecting the application. 
      <img src="https://design.visa.com/assets/components/input/input-behaviors-autosuggest.svg" alt="An input field labeled First name (required), filled with the name Alex and an input field partially filled with a last name"/> 
  - Order suggestions intuitively by listing the most likely options first, common selections, or based on previous interaction.
  - Limit options between 5 and 10 to avoid overwhelming users with too many suggestions.
  - Test autosuggest for consistency in function, responsiveness, result accuracy, and visual presentation across browsers.

{/* CHARACTER COUNTER */}
### Character counter
Character counters provide users with real-time feedback of the number of remaining characters and indicate when the limit has been reached. This feature is often used with multi-line or text area fields and helps users plan their entry accordingly. <br/>
- Avoid imposing arbitrary character limits. Instead, set limits that align with the anticipated length of the user's entry or that are based on the actual requirements of the field or technical constraints.

  {/* DO + DON'T */}

  

  

{/* CLEAR TEXT BUTTON */}
### Clear text button
Clear text button within input is a user interface (UI) element that allows users to quickly and easily erase all the text in a field. This is typically represented by a small 'x' or similar icon within the field itself and facilitates quick erasure for new entries, such as in search fields.

        <img src="https://design.visa.com/assets/components/input/input-behaviors-clear-text.svg" alt="The navigation area of an application with a search input field and some suggested search results in a menu. The input field shows typed entry and a clear text icon button."/> 
 

  - Only include a clear button only when useful for resetting to a blank state, such as search fields. 
  - Avoid clear buttons for short input fields like age or zip code, where users can easily delete characters.
  - Provide immediate feedback by instantly clearing the text field when button is selected.
  - If possible, provide a way to undo the action, in case the button is selected accidentally.

{/* DO + DON'T */}
  

{/* FLEXIBLE INPUT */}
### Flexible input
Flexible input, which allows users to input information in a variety of formats, enhances user-friendly experiences. It eases cognitive load, boosts efficiency, and caters to regional preferences. For example, when asking for a phone number, accept the number with or without dashes, parentheses, or country codes. Similarly, for a date field, accept input in different formats like "MM/DD/YYYY", "DD-MM-YYYY", "Month Day, Year". Learn more about formatting dates in [Grammar and punctuation](https://design.visa.com/content/grammar#date-and-time).

        <img src="https://design.visa.com/assets/components/input/input-behaviors-flexible.svg" alt="An input field for phone number entry that allows for any format"/> 
  

  - Work with developers early and often to ensure robust validation is in place to confirm data is in an acceptable format.
  - Test all possible input scenarios to ensure your flexible input works as expected and handles edge cases gracefully.
  - Be mindful of the potential performance impact as each input variation requires different processing and validation logic.

{/* CONTENT */}
## Content
  - Use simple language—avoid abbreviations or jargon. 
  - Use sentence case, except for proper nouns or acronyms.nput fields have optional behaviors and features you may implement based on use case. Learn about these below. 

{/* LABELS */}
### Labels

  - Limit labels to a maximum of three words. 
  - Ensure labels accurately represent the expected input to reduce errors.
  - Use parallel structure across labels, using either nouns like "Email" or verbs like "Enter email".

{/* LABELS */}
### Inline message

  - Limit all inline messages (including errors) to one to two short sentences with punctuation.
  - Use inline messages to provide additional guidance such as format or specific syntax or values to help avoid errors.
  - Provide concise, descriptive, and helpful guidance about the field's usage and necessity, avoiding technical jargon.

#### Inline error message

  - Use inline error messages to draw attention and to errors without causing frustration.
  - Provide clear, prescriptive guidance on correcting the error. Avoid redirecting users to another page to fix it. 
  - Communicate whether the problem can occur again and offer an alternative backup solution in case it does. 

{/* DO + DON'T */}

  
  


---

# accessibility

---
title: Link
description: Text-based navigation elements that take users to another destination.
meta_description: Find accessibility guidelines for text-based navigation elements that take users to another destination.
thumbnail: assets/components/link-graphic.svg
tab_order: 2
---

## Best practices

- Use an `aria-label`  when the link text alone does not convey enough information to a screen reader.
- Ensure `aria-labels` include context to indicate where the link leads, especially if the link is visually grouped in a template. For example, use “Learn more about [something]”.
- Ensure the `aria-label` always starts with the visible link text.
- When a link opens or downloads other formats (e.g., .pdf, .mp3), ensure the label indicates this, such as `aria-label=&quot;[link text] (file type)&quot;`.
- Indicate when links open in new tabs or pages using `aria-label=&quot;[link text] (opens in a new tab)&quot;`
- Use `rel=&quot;noreferrer noopener&quot;` on external links for added security.

<img src="https://design.visa.com/assets/components/link/accessibility-bp.svg" alt="Two dialogs with similar link titles annotated to show the unique aria-labels for each link."/>

## Keyboard controls

Keyboard actions and their corresponding behaviors for links

- Key: Activates link.



---

# index

---
title: Link
tab_title: Code
description: Text-based navigation elements that take users to another destination.
meta_description: Get code for text-based navigation elements that take users to another destination.
thumbnail: assets/components/link-graphic.svg
---

## Component Code Examples: link

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the link component
const component = parsed.components.find(c => c.name === 'link');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `link`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Link
description: Text-based navigation elements that take users to another destination.
meta_description: Learn how to use text-based navigation elements that take users to another destination.
keywords: ["Hyperlink", "anchor link"]
related: 
  components: 
    - button
    - anchor-link-menu
tab_order: 1
---

{/* INTRO */}
 
Links are text-based navigational elements that take users to another destination. They may appear as standalone elements or inline with text. Links are commonly used in menus, navigation components, panels, and resources like FAQs.<br/><br/>
Also known as: Hyperlink, anchor link.

## Anatomy

  <img src="https://design.visa.com/assets/components/link/link-anatomy.svg" alt="An example link with callout A indicating the icon, another example link with callout B indicating the destination label and callout C indicating the trailing icon, and a third example link with an underline."/>    

  **A. Leading icon (optional):** Icon located before the link text used to enhance the meaning of the link. <br/>
  **B. Destination label (required):** Text indicating where the link will take the user. <br/>
  **C. Trailing icon (optional):** Icon located after link to indicate the meaning of the text. <br/>
  **D. Underline (optional):** Line under link text to enhance and indicate a link is present. 

## Usage

  When to use and when not to use different types of links

- Component: For links that appear outside of sentences or paragraphs.
- When to use: To prompt an action or event. Use a [Button](https://design.visa.com/components/button) instead.

- Component: For links that appear within sentences or paragraphs.
- When to use: To prompt an action or event. Use a [Button](https://design.visa.com/components/button) instead.<br/><br />
          In native mobile applications.

## Best practices
  - Only use links as navigation elements, not for actions. Use a [Button](https://design.visa.com/components/button) to perform actions.
  - Use consistent styling for all links across your experience to ensure users recognize them. 
  - Ensure icons and link text are the same color. 
  - Ensure users can select a link anywhere on the link text or associated icon.
  - Always use an icon to indicate if a link opens in a new tab. Reference [VGAR INT-5](https://bookmarks.visa.com/VGAR-INT-5) for more information.
  - Ensure the visible link text closely matches the name of the resource being linked to.
  - Ensure links are clearly identifiable by pairing text color with an icon or underline. This does not apply to navigation components like horizontal or vertical navigation, anchor link menus, and footers, where text color alone suffices.

{/* ----------- DO + DON'T ----------*/}

{/* ----------- STANDALONE LINKS ----------*/}

  ### Standalone links
    Standalone links are interactive elements placed outside of body text. They’re often used in menus, footers, and sidebars for quick access to frequently used features within the site or application, or in resource lists to provide access to external sites.

{/* ----------- DO + DON'T ----------*/}

{/* ----------- INLINE LINKS ----------*/}

  ### Inline links
  
    Inline links are interactive elements embedded within body text. Inline links are commonly used to provide direct access to additional information or resources without disrupting the flow of the content. 
    - Limit the number of inline links within a paragraph to avoid overwhelming users. 
    - Ensure inline links are relevant to the surrounding content.

{/* ----------- DO + DON'T ----------*/}

{/* ----------- EXTERNAL LINKS ----------*/}

  ### External links
    Users should be aware of, and have control over, whether they are leaving their current website. To ensure users have choice, make sure to indicate when a link leads to an external website. <br/> <br/>
    Generally, there are two methods to inform users that links lead to external sites.

{/* ----------- MAXIMIZE ICON + NO ICON ----------*/}

  
                     
              #### Maximize icon
  
                The most common method is pairing a maximize icon with links to external sites.
     
                <img src="https://design.visa.com/assets/components/link/link-bp-external-maximize.svg" alt="A link with an open window trailing icon."/>
              
                - For standalone links without supporting content, use a maximize icon to indicate the link leads to a new website. 
                - Use the “maximize-link” icon to ensure the line height of the link text is aligned with the icon.
                      
            
                      
              #### No icon
             
                In some scenarios, the link label and surrounding content will provide enough context.
              
              <img src="https://design.visa.com/assets/components/link/link-bp-external-noicon.svg" alt="A link in the middle of a sentence labeled 'Personal finance guide' without any icons."/>
              
                - For standalone links, use labels with the name of the destination when omitting the maximize icon. 
                - For inline links, use surrounding content to indicate the link destination without disrupting the flow of content.         
            
    

{/* ----------- NEW WINDOW OR TAB ----------*/}

### New window or tab

  Generally, avoid opening new windows or tabs. Instead, open links in the current window to avoid disorienting users and causing accessibility problems. Only open a new tab or window when directing users to information that will help them complete a task.
  - Always use an icon to indicate when a link opens in a new window or tab. This is especially important for assistive technology users, as new tabs can be disruptive or disorienting. For more information, reference [VGAR INT-5](https://bookmarks.visa.com/VGAR-INT-5).

{/* ----------- "BACK" TO LINKS ----------*/}

  ### "Back to" links

    A "Back to" link can be used as an extra navigation element to take users back one level in the site hierarchy. “Back to” links are generally paired with a backwards-facing arrow.
    - Always indicate where the “back to” link will take users.  

{/* ----------- DO & DONT'S ----------*/} 

## Behaviors

### Styling and coding buttons and links

  In general, buttons should be used for in-page actions and links should be used as navigational tools, like leaving a page. Whenever possible, match the visual styling of these elements with their coded and user-expected behavior. However, buttons and links may be styled like one another in some cases. Learn about these exceptions below.

    
                     
              #### Button coded as links

              <Typography variant="body-2">Buttons may be coded as links but styled as buttons when necessary. For example, an icon button may be appropriate when linking to a shopping cart.</Typography>

              <img src="https://design.visa.com/assets/components/link/button-behavior-linkbutton.svg" alt="A primary button labeled 'Checkout' with a right chevron trailing icon, a secondary button labeled 'Visit cart' with a right chevron trailing icon, and a UI shopping cart icon button"/>

              <Typography variant="body-2">Use the arrow icon whenever possible as a visual cue that selecting will navigate to another page.</Typography>          
            
                      
              #### Link coded as buttons
              
              <Typography variant="body-2">Links may be coded as buttons but styled as links when necessary. For example, buttons may be styled as links when information will be presented in an overlay or dialog.</Typography>
            
              <img src="https://design.visa.com/assets/components/link/button-behavior-buttonlink.svg" alt="Three links each with a leading icon."/>
            
              <Typography variant="body-2">Avoid underlining links coded as buttons, as this style is reserved for links, not buttons.</Typography>          
            
      

## Content

  - Use simple language—avoid abbreviations or jargon. 
  - Avoid verbs that focus on senses to include all users. For example, use “Visit cart,” instead of “View cart”.
  - Use at least two but no more than five words in link labels, unless linking the name of a resource or publication. 
  - Avoid using articles such as “a,” “an,” or “the”. 
  - Avoid using “click here,” or “here” as link text.
  - Don’t include "link" in link text.

### Link formulas

  - Combine action or command verbs with nouns to make labels specific.
    - [verb] + [noun] is useful for most product cases.
    - [verb] + [adverb] is typically used for marketing and promotions.
  - Only use single word labels for common navigational actions such as “Home,” “Profile,” or “Settings”.

{/* ----------- DO & DONT'S ----------*/}

### Standalone links
  - Use sentence case except for acronyms or proper nouns, such as resource titles. 

{/* ----------- DO & DONT'S ----------*/}

### Inline links

  - Follow the capitalization structure of text surrounding inline links. Only capitalize proper nouns, acronyms, or titles. 

{/* ----------- DO & DONT'S ----------*/}

## Platform considerations

### Mobile
Avoid using inline links in native mobile apps, as they can be difficult to select on small screens. If your use case requires inline links in a native mobile app, ensure you implement sufficient touch targets.
<img src="https://design.visa.com/assets/components/link/link-platform-mobile.svg" alt="An inline link in a mobile interface"/>


---

# accessibility

---
title: List item
description: Individual containers that can be grouped to create lists in mobile apps.
meta_description: Get code for individual containers that can be grouped to create lists in mobile apps.
thumbnail: assets/components/list-item-graphic.svg
tab_order: 3
---

## Best practices

An HTML ordered `ol` or unordered `ul` list should have only list items `li` as direct children, and list items should have only lists as direct parents. It’s a common mistake to place other HTML elements such as `div`s as direct children of lists, especially as containers for conditional content. List items may have HTML elements within them, including other lists. 
For Angular and React, use a container that doesn’t render such as `ng-container` or `<></>`.
- Use semantic HTML and ARIA roles for lists and list items so that assistive technologies recognize them as part of a list structure. Lists are landmarks and can be used for keyboard navigation. Screen readers announce the item number in ordered lists, and can announce the total number of items in lists. 
- If a list item is interactive, its accessible name should match its visible label. Focus should move through list items in a meaningful, logical order.
- Include appropriate text alternatives for icons or images within a list item.
- Don’t use list markers to convey important information. They’re pseudo-elements, meaning they aren’t focusable or clickable and are inaccessible to screen readers.
- Use [logical CSS](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values)<!-- aria-label="Logical CSS (opens in a new tab)" --> for the contents of a list item to ensure it switches seamlessly between right-to-left (RTL) and left-to-right (LTR) modes.



---

# index

---
title: List item
tab_title: Code
description: Individual containers that can be grouped to create lists in mobile apps.
meta_description: Get code for individual containers that can be grouped to create lists in mobile apps.
thumbnail: assets/components/list-item-graphic.svg
---

## Component Code Examples: list-item

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the list-item component
const component = parsed.components.find(c => c.name === 'list-item');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `list-item`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples


---

# usage

---
title: List item
description: Individual containers that can be grouped to create lists in mobile apps.
meta_description: Learn how to use individual containers that can be grouped to create lists in mobile apps.
keywords: ["List element", "list entry", "UITableViewCell (iOS)", "View (Android)"]
related:
  components:
    - accordion
    - checkbox
    - radio
    - switch
tab_order: 1
---

A list item is an individual container used to represent options in a list within mobile apps. List items can vary functionally and visually based on the needs of the app or interface.<br/><br/>
Also known as: List element, list entry, UITableViewCell (iOS), View (Android).

## Anatomy
<img src="https://design.visa.com/assets/components/list-item/listitem-anatomy.svg" alt="Vertically stacked four list items with leading icons, a title and hyperlink at the top, with callout A indicating the title, callout B indicating the leading icon, callout C indicating the lead text, callout D indicating the optional divider, and callout E indicating the hyperlink."/>
**A. List title (optional):** Label used to group list items.<br/>
**B. Hyperlink (optional):** Link that navigates users to a new screen, often to show more content.<br/>
**C. Leading visual element (optional):** Element, such as avatar, icon, or image, used to represent the list item.<br/>
**D. List item (required):** Label representing the individual list item option.<br/>
**E. Divider (optional):** Visual element separating the items in a list.<br/>

## Usage
When to use and when not to use different types of list items

- Component: To display a simple list of options or information.
- When to use: If the list content needs to be nested more than one level deep and becomes overly complex or lengthy.

- Component: If each item in the list navigates to a different page or section.
- When to use: If the list content is simple and doesn’t need to be expanded.

- Component: To allow users to turn on or off certain options in the list. <br></br><br></br>For settings or preference interfaces.
- When to use: To switch between alternate options or content views. Use a [toggle](https://design.visa.com/components/toggle-button) instead.

- Component: If users can select multiple options from the list.
- When to use: If options on the list are mutually exclusive.

- Component: If users can select only one option from the list.
- When to use: If users may need to select more than one option from the list.

## Best practices
- Organize content logically and predictably to help users scan information easily.
- Use icons, avatars, or images consistently to enhance the meaning of list items or to provide additional context.
- Consider implementing a scroll bar once the list reaches a maximum height to allow access to all options without overwhelming the user. 

### Static list item
Static list items are options within a list that users can’t interact with. They only display information and don’t give users the option to select or change the values.
<img src="https://design.visa.com/assets/components/list-item/listbox-static.svg" alt="Vertically stacked four list items with leading icons listing transactions, their costs, and remaining balance, and a title stating Transactions and hyperlink at the top to See more."/>
- Use static list items to present data that doesn’t need to be changed.

### Clickthrough list item
Clickthrough list items act as buttons or links that navigate users to a new page or open additional content upon selection.
<img src="https://design.visa.com/assets/components/list-item/listitem-clickthrough.svg" alt="Vertically stacked four, clickable list items titled Recent transactions, Offers and rewards, Tax documents, and Retirement planning."/>
- Clearly indicate that options lead to more information by using visual cues like the arrow icon.
- Ensure the entire list item container is clickable, not just the trailing icon.
- Follow all [Link guidance](https://design.visa.com/components/link) for implementing clickthrough list items.

### Switch list item
Switch list items enable users to toggle between two states, usually “on” or “off”. They’re typically used for settings or features that can enabled or disabled.
<img src="https://design.visa.com/assets/components/list-item/listitem-switch.svg" alt="Vertically stacked two list items with leading icons titled Email notifications and Text notifications with switches next to each."/>
- Avoid using switches for irreversible actions.
- Follow all [Switch guidance](https://design.visa.com/components/switch) for implementing switch list items.

### Checkbox list item
Checkbox list items allow users to select multiple options from a list. Each list item has an associated checkbox that users can check or uncheck. Use checkboxes for multi-select scenarios where users might want to choose more than one item.
<img src="https://design.visa.com/assets/components/list-item/listitem-checkbox.svg" alt="Vertically stacked three list items titled Privacy settings with a hyperlink to view advanced settings. Each list item has a checkbox."/>
- Provide immediate visual feedback when a checkbox is selected or deselected to confirm the user's action.
- Follow all [Checkbox guidance](https://design.visa.com/components/checkbox) for implementing checkbox list items.

### Radio list item
Radio list items enable users to select only one option from a list of options. Each item has an associated radio button and selecting one option deselects any previously selected option.
<img src="https://design.visa.com/assets/components/list-item/listitem-radio.svg" alt="Vertically stacked four list items titled Preferred payment method. Each list item has a radio button and the first option, Credit card, is selected."/>
- Clearly indicate the selected state of a radio list item.
- Follow all [Radio guidance](https://design.visa.com/components/radio) for implementing radio list items.

## Platform considerations

### Web
List items can also be utilized in web and responsive web applications. Ensure that list items adapt to different screen sizes by allowing option labels to reflow with the container.

<img src="https://design.visa.com/assets/components/list-item/link-platform-mobile.svg" alt="A settings page with list items that have short lines of text."/>

## Content
- Always use sentence case except for proper nouns or acronyms.
- Use plain language and avoid abbreviations or jargon.
- Avoid using long lines of text, as it decreases readability.
- Reference [Content](https://design.visa.com/content) for additional guidance on crafting content within apps and experiences. 

### Labels 
- Limit labels to three to five words when possible.
- Be consistent when using plural language or “(s)” in field labels. For example, use “Card type,” “Card types,” or “Card type(s)” consistently. If using “(s),”, use the asterisk method over “(required)” to keep labels concise. 
- Avoid using unnecessary articles like “the” or “an,” unless they’re included in the proper name of a product or service.  
- Use parallel structure across field labels, using either nouns like "Services" or verbs like "Select a service". Learn more about parallel structure in [Grammar and punctuation](https://design.visa.com/content/grammar#parallel-structure).


---

# accessibility

---
title: Listbox
tab_order: 2
description: Container that displays a list of items available for selection.
meta_description: Find accessibility guidelines for containers that display a list of items available for selection.
thumbnail: assets/components/select-listbox-graphic.svg
---

## Best practices

<br/>
**Note:** VPDS Listbox components are used within other components such as [Multiselect](https://design.visa.com/components/multiselect) and [Combobox](https://design.visa.com/components/combobox). [Dropdown menu](https://design.visa.com/components/dropdown-menu) components aren't listboxes. They use listbox CSS classes but function differently and have different roles.<br/><br/>
An element with `role=&quot;option&quot;` cannot have any form controls within it. In some implementations, the “checkboxes” within multi-select listboxes are spans styled to look like checkboxes. 
- Use the up and down arrow keys to cycle through the options. Using the Tab key will move the focus to the next focusable element after the listbox.

## Keyboard controls

### All vertical oriented listbox

Keyboard actions and their corresponding behaviors for vertical oriented listbox

- Key: Navigates to an item.

- Key: Moves the focus to the first listbox item. Recommend for lists with more than five items.

- Key: Moves the focus to the last listbox item. Recommend for lists with more than five items.

- Key: Moves to the next element in the form. Persist and maintain the view within the listbox when focus moves to the next element.

- Key: Moves focus onto the previously selected item. Note that this function is only true when the keyboard focus is one element next to listbox.

### Multi-select listbox

Keyboard actions and their corresponding behaviors for multi-select listbox

- Key: Checks/unchecks the checkbox when the component is in focus.

- Key: Selects consecutive items from the most recently selected item to the focused item.

- Key: Moves the focus to and toggles the selected state of the previous item.

- Key: Moves the focus to and toggles the selected state of the next item.



---

# index

---
title: Listbox
tab_title: Code
description: Container that displays a list of items available for selection.
meta_description: Get code for containers that display a list of items available for selection.
thumbnail: assets/components/select-listbox-graphic.svg
categories:
  - actions
  - selection-controls
---

## Component Code Examples: listbox

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the listbox component
const component = parsed.components.find(c => c.name === 'listbox');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `listbox`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Listbox
description: Container that displays a list of items available for selection. 
meta_description: Learn how to use containers that display a list of items available for selection.
keywords: ["List", "menu", "dropdown", "UIPickerView (iOS)", "Spinner (Android)", "Menu (Android)", "MenuItem (Android)"]
related:
  components:
    - combobox
    - dropdown-menu
tab_order: 1
---

Listboxes are a container that organize and display items in a list format. They enable users to select one or more items in a list, navigate to a page, or perform an action. They are a key element in user interfaces and form the foundation for select menus like [Combobox](https://design.visa.com/components/combobox) and [Multiselect](https://design.visa.com/components/multiselect), as well as [Horizontal navigation](https://design.visa.com/components/horizontal-navigation) and [Dropdown menus](https://design.visa.com/components/dropdown-menu) to perform actions.<br/><br/>

Also known as: List, menu, dropdown, UIPickerView (iOS), Spinner (Android), Menu (Android), MenuItem (Android).

## Anatomy
<img src="https://design.visa.com/assets/components/listbox/listbox-anatomy.svg" alt="An example single-select listbox with list items, featuring callout A indicating the required label, callout B indicating the container menu, and callout C indicating the optional scrollbar. Another example of a multi-select listbox with list items, featuring callout D indicating the required items and callout E indicating the optional inline message."/>
**A. Label (required):** Text summarizing the items available for selection. <br/>
**B. Menu (required):** Container displaying the list of items that includes scrollbar. <br/>
**C. Scrollbar (optional):** Control allowing users to navigate long menus. <br/>
**D. Item (required):** Selectable text representing a single item.<br/>
**E. Inline message (optional):** Brief text describing the label in more detail. 

## Best practices
- Always keep the context in which the listbox is being used in mind to ensure the best possible user experience.

## Usage
When to use and when not to use different types of listboxes

- Component: To present a list of items when the user can only select one.<br/><br/>
            For long lists where all items can't be viewed at once or require scrolling.<br/><br/>
- When to use: For fewer than four items or short lists that can be viewed without scrolling. Use a [radio button group](https://design.visa.com/components/radio)instead. <br/><br/>
        For long lists when users would benefit from entering text to filter or search the list items. Use a [combobox group](https://design.visa.com/components/combobox) instead. <br/><br/>
        If space is limited and displaying items in a collapsible menu would help. Use [select (native)](https://design.visa.com/components/select) instead. <br/><br/>
        To present a list of actions. Use a [dropdown menu](https://design.visa.com/components/dropdown-menu) instead.

- Component: To present a list of items where the user can select one or multiple. <br/><br/>
            For long lists where all items can't be viewed at once or require scrolling.
- When to use: For fewer than four items or short lists where all items can be viewed without scrolling. Use a [checkbox button group](https://design.visa.com/components/checkbox) instead. <br/><br/> 
            For long lists where users would benefit from entering text to filter or search the list items. Use a [multiselect](https://design.visa.com/components/multiselect) instead. <br/><br/>
            If space is limited and displaying items in a collapsible menu would help. Use a [multiselect](https://design.visa.com/components/multiselect) instead.

- Component: As menus for a components including multiselect, combobox, dropdown menu, navigation menu.
- When to use: When presenting items doesn’t require user interaction to expand the list. Use a single- or multi-select listbox instead.

### Using in forms
Listboxes are commonly used as a selection control in an always expanded state within forms or on page. They provide users with a straightforward and efficient way to select single or multiple items from a list. Unlike dropdown menus, where items are hidden until interaction, the always expanded state of a listbox allows all items to be visible and directly accessible.
- Consider the length and complexity of your list, aiming to a small to medium number of items.
- Combine with scroll behaviors for longer lists to ensure ease of navigation. 

#### Single-select listbox (radio)

Single-select listboxes are coded as radio buttons, allowing users to select only one item from the list at any given time. 
<img src="https://design.visa.com/assets/components/listbox/listbox-single.svg" alt="A single-select listbox labeled 'Country of residence' with countries as list items"/>
- Follow all [Radio guidance](https://design.visa.com/components/radio) for implementing single-select listboxes.

#### Multi-select listbox (checkbox)

Multi-select listboxes are coded as checkboxes, allowing users to select multiple items from the list at once. 
<img src="https://design.visa.com/assets/components/listbox/listbox-multi.svg" alt="A multi-select listbox labeled 'Filter by category' with credit cards as list items"/>
- Follow all [Checkbox guidance](https://design.visa.com/components/checkbox) for implementing single-select listboxes. 

#### Pre-selected items

While some native select components may have an item preselected by default, listboxes should generally not have any preselected items upon page load. This ensures users are not influenced by any preconceived selections and can make their own choices based on their specific needs and preferences. <br/><br/>
**Note:** In some cases, the listbox may load with a preselected item. This is usually due to a user setting or a saved configuration in which the user previously selected the item(s). 
<img src="https://design.visa.com/assets/components/listbox/listbox-preselected.svg" alt="A single-select listbox labeled 'State (required)' without any state list item preselected."/>

### Using as menus
Listboxes are used as the foundation for multiple components like navigation menus, dropdown menus, multiselect, and combobox. In these cases, the behavior of the listbox may be modified to suit the needs of the component. Always consult with accessibility partners before modifying these behaviors further.

### Optional vs. required labels
Always ensure required fields are clearly labeled. While this may seem repetitive, it helps users scan for necessary information and reduces errors. There are two methods for labeling required fields based on your use case. Whichever method you select, use it consistently across your experiences. <br/><br/>
**Note:** Previous VPDS guidance recommended only marking optional fields. Our guidance has been updated to reflect current [Nielsen Norman Group](https://www.nngroup.com/articles/required-fields/)<!-- aria-label="Nielsen Norman Group (opens in a new tab)" --> recommendations. Learn more about optional vs. required labels in [Forms](https://design.visa.com/patterns/forms/#optional-vs-required-labels).

                    
              ### “Required” in the label (preferred method)
              
              <Typography variant="body-2">Including “required” within the label ensures it’s easy to find, particularly when instructions at the top might not be visible while scrolling. This method bolsters accessibility for both sighted and non-sighted users. </Typography>  
              
                <img src="https://design.visa.com/assets/components/listbox/listbox-mark-required.svg" alt="A listbox component with 'required' in the label"/>
              
              - Mark all fields that are required. This ensures you’re as explicit and transparent as possible.
              - Include “(required)” in field label with a space between the last word and the first parenthesis. 
                 
          
                    
              ### Asterisk in the label (alternative method)
              <Typography variant="body-2">
              Asterisks are commonly used to indicate required fields. The main advantage to using this method is that it doesn’t take up much space, helps users along a common edge, and can be used in addition to formatting hints in the label. 
              </Typography>
              
              <img src="https://design.visa.com/assets/components/listbox/listbox-asterisk.svg" alt="A listbox component with an asterisk in the label indicating a required field"/>
              
                - Always include a legend or key at the top of the content area noting that the asterisk indicates a required field.
                - Place the asterisk at the beginning of the label with a space between the symbol and the first word.
          
    

### When required is implied
Although it's usually recommended to label required fields, there are cases where it’s implied that the field is required. This is common when there’s a one or two fields fundamental to completing of a task, like the username and password fields on a login screen. In these cases, marking the fields required isn’t necessary but can add additional clarity.

### Labeling optional fields
It’s not generally necessary to mark which fields are optional. While doing so can support clarity, it also adds unnecessary visual noise. Whatever you choose, apply the choice consistently to avoid confusion.

## Content
- Always use sentence case except for proper nouns or acronyms.
- Use plain language and avoid abbreviations or jargon.
- Reference [Content](https://design.visa.com/content) for additional guidance on crafting content within apps and experiences. 

### Labels
- Limit labels to three to five words when possible.
- Be consistent when using plural language or “(s)” in field labels. For example, use “Select card type,” “Select card types,” or “Select card type(s)” consistently. If using “(s)”, use the asterisk method over “(required)” to keep labels concise. 
- Use parallel structure across field labels, using either nouns like "Services" or verbs like "Select a service". Learn more about parallel structure in [Grammar and punctuation](https://design.visa.com/content/grammar).

### Item labels
- Limit item labels to three words or fewer unless referencing proper nouns, such as product names. 
- Avoid using unnecessary articles like “the” or “an,” unless they’re included in the proper name of a product or service.  

### Inline messages
- Use full sentences with proper punctuation. 
- Limit descriptions to 80 characters or 20 words including spaces.
- Provide useful information such as why a field is required (if not obvious) without being technical.
- Give an example or specific syntax or values for inputs to help avoid errors.

#### Inline error message

- Use inline error messages to draw attention and to errors without causing frustration.
- Provide clear, prescriptive guidance on correcting the error. Avoid redirecting users to another page to fix it. 
- Communicate whether the problem can occur again and offer an alternative backup solution in case it does. 

---

# accessibility

---
title: Multiselect
description: Control that allows users to select multiple options from a dropdown menu.
meta_description: Find accessibility guidelines for controls that allow users to select multiple options from a dropdown menu.
thumbnail: assets/components/select-multiselect-graphic.svg
tab_order: 2
---

## Best practices

<br/>
**Note:** Multiselects are a composite of native HTML elements. Follow the latest examples to ensure these elements are accessible using the keyboard and screen readers.
- This component can display a message when no options are found. 
- Note that the multiselect menu is a listbox component. It uses elements with the role of “option” which doesn’t allow other form controls inside them. The “checkboxes” are not actual checkbox inputs.
- Maintain common keyboard shortcuts used for editing text unless the use case requires a different behavior. Reference [Input](https://design.visa.com/components/input) for more.

## Keyboard controls

### Input

Maintain common keyboard shortcuts used for editing text unless uniquely specified. Refer to [Input](https://design.visa.com/components/input) for details.

Keyboard actions and their corresponding behaviors for input

- Key: Moves to the next interactive focusable element

- Key: Moves to the previous focusable element

- Key: Opens the menu.

### Menu (listbox pop-up)

Reference [Listbox](https://design.visa.com/components/listbox) for detailed interactions. Focus will loop in a circular direction among the menu items.

Keyboard actions and their corresponding behaviors for menu (listbox pop-up)

- Key: Selects the focused highlighted option.

- Key: Dismisses menu and clears any inline autocomplete while maintaining user-entered input.

- Key: Moves to the next interactive focusable element and closes the menu.

- Key: Moves to the previous focusable element and closes the menu.

- Key: - Moves between the options when the menu is open. 
        - Arrow key interaction will loop focus within the options. When focus is on the last option within the set, the right/down arrow keys will move focus to the first option. When focus is on the first option within the set, the left/up arrow key will move focus to the last option.



---

# index

---
title: Multiselect
tab_title: Code
description: Control that allows users to select multiple options from a dropdown menu.
meta_description: Get code for controls that allow users to select multiple options from a dropdown menu.
thumbnail: assets/components/multiselect-graphic.svg
categories:
  - actions
  - selection-controls
---

## Component Code Examples: multiselect

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the multiselect component
const component = parsed.components.find(c => c.name === 'multiselect');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `multiselect`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Multiselect
description: Control that allows users to select multiple options from a dropdown menu. 
meta_description: Learn how to use controls that allow users to select multiple options from a dropdown menu.
keywords: ["Multi-select menu", "multiple select dropdown", "multi-select combobox", "multi-option selector", "multi-selector"]
related:
  components:
    - combobox
    - listbox
tab_order: 1
---

Multiselect components enable users to select one or more checkboxes from a menu. This component combines an input field and multiselect listbox to ensure users can find and select options quickly.<br/><br/>

Also known as: Multi-select menu, multiple select dropdown, multi-select combobox, multi-option selector, multi-selector.

## Anatomy
<img src="https://design.visa.com/assets/components/multiselect/multiselect-anatomy.svg" alt="A multiselect with a label and an inline message, featuring callout A indicating the required label, callout B indicating the inline message, and callout C indicating the chevron icon button. Another multiselect with a selected option, featuring callout D indicating the required input and callout E indicating the required option, and an expanded menu with callout F indicating the required menu. Another multiselect with chips inside the input field, featuring callout G indicating a removable compact chip, and select and clear buttons with callout H indicating the optional buttons."/>
**A. Label (required):** Text summarizing the options available for selection.<br/>
**B. Inline message (optional):** Brief text describing the field label in more detail.<br/>
**C. Chevron icon button (required):** UI icon button that expands or collapses menu.<br/>
**D. Input (required):** Text field enabling users to enter text to filter menu options. <br/>
**E. Option (required):** Selectable text representing a single option.<br/>
**F. Menu (required):** Container displaying list of options that includes scrollbar as needed.<br/>
**G. Removable compact chip (required):** Chip component representing a selected option.<br/>
**H. Select and clear all buttons (optional):** Button pair allowing users to select or clear all options.

## Usage

When to use and when not to use different types of multiselects

- Component: To present a list of options where the user can select one or multiple.<br/><br/>
            For long lists where all options can't be viewed at once or require scrolling.<br/><br/>
            If users would benefit from entering text to filter or search the list of options.<br/><br/>
            If space is limited and displaying options in a collapsible menu would help.
- When to use: If users can only select one option. Use a [Combobox](https://design.visa.com/components/combobox) instead.<br/><br/>
            For short lists where all options can be viewed without scrolling. Use a [Checkbox group](https://design.visa.com/components/checkbox/usage#checkbox-groups) instead.<br/><br/>
            To present a list of actions. Use a [Dropdown menu](https://design.visa.com/components/dropdown-menu) instead.

- Component: If users might want to select all or most options.
- When to use: If users won’t likely select all or most options.

## Best practices
- Use checkbox states for multiselect options to ensure they appear visually different when selected and unselected.
- Ensure users can select anywhere within a checkbox or associated option label to choose an option.
- List options in a logical order, either alphabetically or according to the most common or likely selection.
- Ensure multiselect components appear collapsed on page load to save space. 
- Follow [Checkbox guidance](https://design.visa.com/components/checkbox) for implementing checkboxes within the menu. 

### Select/clear all buttons
Multiselect components can optionally include select all/clear all controls. These enable users to easily select or unselect all options. 
<img src="https://design.visa.com/assets/components/multiselect/multiselect-select-clear.svg" alt="An expanded multiselect component with select all/clear all buttons"/>
- Include select/clear all controls in any case where users may want to select all or most options in the menu. 
- Use destructive styling for the “clear all” control to prevent accidental clearing.

### Chevron direction
The chevron UI icon button enables users to manually expand or collapse the menu. The direction it points should indicate what happens when it’s selected.

         
          #### Collapsed
          
            The chevron should point down when the menu is collapsed.
            <img src="https://design.visa.com/assets/components/multiselect/combobox-behaviors-chevron_include.svg" alt="An example Multiselect with collapsed menu"/>
            - Allow users to expand the menu by selecting anywhere in the input field, not just the chevron icon.  
      
         
          #### Expanded

            The chevron should point up when the menu is expanded.
          <img src="https://design.visa.com/assets/components/multiselect/combobox-behaviors-chevron_include-1.svg" alt="An example Multiselect with expanded menu"/>
          - Allow users to collapse the menu by removing focus from the field, not just by using the chevron icon.    
      

### Empty state
Empty states occur when text in the input field doesn’t match any menu options. This helps guide users with useful feedback about their input. 
<img src="https://design.visa.com/assets/components/multiselect/multiselect-empty.svg" alt="An expanded multiselect component with 'no results found' in the menu"/>
- Use clear language to inform users that their input doesn’t match any options, as users may misinterpret an empty state for a loading state and wait for options to appear.

### Optional vs. required labels
Always ensure required fields are clearly labeled. While this may seem repetitive, it helps users scan for necessary information and reduces errors. There are two methods for labeling required fields based on your use case. Whichever method you select, use it consistently across your experiences. <br/><br/>
**Note:** Previous VPDS guidance recommended only marking optional fields. Our guidance has been updated to reflect current [Nielsen Norman Group](https://www.nngroup.com/articles/required-fields/)<!-- aria-label="Nielsen Norman Group (opens in a new tab)" --> recommendations. Learn more about optional vs. required labels in [Forms](https://design.visa.com/patterns/forms/#optional-vs-required-labels).

                    
              ### “Required” in the label (preferred method)
              
              <Typography variant="body-2">Including “required” within the label ensures it’s easy to find, particularly when instructions at the top might not be visible while scrolling. This method bolsters accessibility for both sighted and non-sighted users. </Typography>  
              
                <img src="https://design.visa.com/assets/components/multiselect/input-mark-required.svg" alt="A collapsed multiselect component with 'required' in the label"/>
              
              - Mark all fields that are required. This ensures you’re as explicit and transparent as possible.
              - Include “(required)” in field label with a space between the last word and the first parenthesis. 
                 
          
                    
              ### Asterisk in the label (alternative method)
              <Typography variant="body-2">
              Asterisks are commonly used to indicate required fields. The main advantage to using this method is that it doesn’t take up much space, helps users along a common edge, and can be used in addition to formatting hints in the label. 
              </Typography>
              
              <img src="https://design.visa.com/assets/components/multiselect/multiselect-asterisk.svg" alt="A collapsed multiselect component with an asterisk in the label indicating a required field"/>
              
                - Always include a legend or key at the top of the content area noting that the asterisk indicates a required field.
                - Place the asterisk at the beginning of the label with a space between the symbol and the first word.
          
    

### When required is implied
Although it's usually recommended to label required fields, there are cases where it’s implied that the field is required. This is common when there’s a one or two fields fundamental to completing of a task, like the username and password fields on a login screen. In these cases, marking the fields required isn’t necessary but can add additional clarity.

### Labeling optional fields
It’s not generally necessary to mark which fields are optional. While doing so can support clarity, it also adds unnecessary visual noise. Whatever you choose, apply the choice consistently to avoid confusion.

## Behaviors

### Input functionality
The multiselect component can be implemented with a search or filter feature that allows users to find their desired option more quickly. Implement whichever method applies best to your use case.<br/><br/>
**Note:** This feature isn’t automatically included in the component build and can be implemented in various ways. Product teams can determine how to load and filter data for their use case and should work closely with developers to determine the appropriate level of complexity for their product.

         
          #### Menu search

            In this method, the text field is used to search the options displayed in the menu. When the user types, the menu jumps so the option that matches their input best appears at the top of the field, and focus is placed on that option. 
            <img src="https://design.visa.com/assets/components/multiselect/multiselect-menu-search.svg" alt="An expanded multiselect component with 'B2B' in the input field and an option containing it appearing at the top of the menu"/>
            - Use this method when users may want to browse options that are similar to their input but don’t match exactly.
      
         
          #### Menu filter

            In this method, the text field is used to filter the options displayed in the menu. When the user types, the options displayed in the menu are temporarily reduced so only those matching the entry remain.
          <img src="https://design.visa.com/assets/components/multiselect/multiselect-menu-filter.svg" alt="An expanded multiselect component with 'B2B' in the input field and only options containing it appearing in the menu"/>
          - Use this method when users are likely to know exactly what option they’re looking for.
      

### Selection method
Mulitselect components don’t require users to confirm their choices after selection. As soon as users select a checkbox in the menu, it appears as a chip in the input field. 
<img src="https://design.visa.com/assets/components/multiselect/multiselect-selection.svg" alt="Two expanded multiselect components demonstrating how placing focus on an option will select the option"/>
- Ensure users can select anywhere within a checkbox or associated option label to choose an option.

### Scaling and reflow
Scaling and reflow refers to how content behaves as the container size changes, particularly when the container is small and can’t display all content at once. This is common with multiselect, as it’s often used when screenspace is limited.<br/><br/>
Labels should always be fully visible when possible. If truncation is necessary, ensure the full-text option is shown in the expanded menu view and only the chip label is truncated. This approach allows screen readers to function as normal and read or render the option label, regardless of truncation, for assistive technology users.
- Scale the input field vertically to fit selection chips until the set maximum height is reached.
- Implement a scrollbar when the maximum height is reached to allow users to access all menu options or selection chips. 

## Content
- Always use sentence case except for proper nouns or acronyms.
- Use plain language and avoid abbreviations or jargon.
- Reference the [Content](https://design.visa.com/content) for additional guidance on crafting content within apps and experiences. 
- Avoid using unnecessary articles like “the” or “an”, unless they’re included in the proper name of a product or service.

### Labels
- Limit field labels to a maximum of three to five words.
- Be consistent when using plural language or “(s)” in field labels. For example, use “Select card type,” “Select card types,” or “Select card type(s)” consistently. If using “(s)”, use the asterisk method to label required fields instead of “(required)” within parenthesis to keep concise. 
- Use parallel structure across field labels, using either nouns like "Services" or verbs like "Select a service". Learn more about parallel structure in the [Grammar and punctuation](https://design.visa.com/content/grammar#parallel-structure). 

### Option labels
- Limit option labels to three words or fewer unless referencing proper nouns, such as product names. 
- Avoid using unnecessary articles like “the” or “an,” unless they’re included in the proper name of a product or service.  
- Consistently order labels across experiences based on logical sequence, either alphabetically or by importance.

### Inline messages
- Use full sentences with proper punctuation. 
- Limit descriptions to 80 characters or 20 words including spaces.
- Provide useful information such as why a field is required (if not obvious) without being technical.
- Give an example or specific syntax or values for inputs to help avoid errors.

#### Inline error message

- Use inline error messages to draw attention and to errors without causing frustration.
- Provide clear, prescriptive guidance on correcting the error. Avoid redirecting users to another page to fix it. 
- Communicate whether the problem can occur again and offer an alternative backup solution in case it does. 

## Platform considerations

### Mobile
The multiselect component opens a full-screen menu and spans the full width of the page on mobile screens. For more, [visit the mobile flow (internal only)](https://bookmarks.visa.com/vpds-visit-the-mobile-flow)<!-- aria-label="visit the mobile flow (internal only) (opens in a new tab)" -->.

<img src="https://design.visa.com/assets/components/multiselect/multiselect-platform-mobile.svg" alt="An example Multiselect on a mobile screen"/>

- Ensure users can exit the fullscreen view by selecting the close button in the top app bar. 
- Remove the chevron icon button from the input field when the menu is in full-screen view.
- Keep the full-screen menu open until users manually exit to ensure they’re finished making selections. 

---

# accessibility

---
title: Navigation drawer
tab_order: 2
description: Collapsible navigation panels that float over page content on small screens.
meta_description: Find accessibility guidelines for collapsible navigation panels that float over page content on small screens.
thumbnail: assets/components/navigation-drawer-graphic.svg
---

## Best practices

<br/>
**Note:** Although the list resembles tabs and uses tab styles, it does not have `tablist` roles or behaviors.
- Use `aria-current=&quot;true&quot;` or `aria-selected=&quot;true&quot;` to set the active tab.
- Make sure users can scroll to all the content within the drawer.
- Ensure `nav` elements have an `aria-label` with a unique and meaningful name. The label text shouldn’t include the word “navigation” as this will be announced automatically and be redundant for the screen reader.
- Implement navigation drawers as `dialog` elements.

### Logos

Our library has a classname just for the application name in the horizontal navigation component. There is a component for the Visa logo that adjusts for the user’s high contrast settings.
- Ensure the logo has an accessible name or is inside a link with an accessible name with `aria-hidden=&quot;true&quot;` on the svg.
- Use one of the library’s classes for high contrast with a custom logo. Choose between the class for a light or dark foreground depending on the custom logo. Setting a contrasting background behind the brand logo ensures it will have maximum contrast in high contrast mode without a visible change in default contrast mode.

## Keyboard controls

Keyboard actions and their corresponding behaviors for navigation drawer

- Key: Activates buttons within the drawer.

- Key: Navigates to the focused element page and activates buttons within the drawer.

- Key: Moves to the next interactive focusable element.

- Key: Dismisses the navigation when the vertical navigation is collapsed into a menu, such as on a mobile viewport.



---

# index

---
title: Navigation drawer
tab_title: Code
description: Collapsible navigation panels that float over page content on small screens.
meta_description: Get code for collapsible navigation panels that float over page content on small screens.
thumbnail: assets/components/navigation-drawer-graphic.svg
categories:
  - navigation
  - structure-and-layout
---

## Component Code Examples: navigation-drawer

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the navigation-drawer component
const component = parsed.components.find(c => c.name === 'navigation-drawer');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `navigation-drawer`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples


---

# usage

---
title: Navigation drawer
tab_title: Usage
tab_order: 1
description: Collapsible navigation panels that float over page content on small screens.
meta_description: Learn how to use collapsible navigation panels that float over page content on small screens.
keywords: ["Drawer menu", "side menu", "flyout menu", "sidebar navigation", "hamburger menu", "collapsible menu", "Navigation Drawer (Android)"]
related:
  components: 
    - vertical-navigation
    - top-app-bar
  content:
    - information-architecture
---

The navigation drawer is a vertical navigation menu used on mobile devices or small web screens. It’s typically accessed from a menu icon in the [Top app bar](https://design.visa.com/components/top-app-bar).<br/><br/>
Also known as: Drawer menu, side menu, flyout menu, sidebar navigation, hamburger menu, collapsible menu, Navigation Drawer (Android).

## Anatomy
<img src="https://design.visa.com/assets/components/navigation-drawer/navdrawer-anatomy.svg" alt="A navigation drawer with 'Visa' featuring callout A indicating the brandmark, callout B indicating the application name, callout C indicating the section title, callout D indicating the leading icon of a link, callout E indicating the link label, callout F indicating the user profile, callout G indicating the close icon button, callout H indicating the expandable button's chevron icon, and callout I indicating the scrollbar."/>

**A. Brand mark (optional):** Visual element representing Visa, a partner brand, or a fictitious brand associated with the product.<br/>
**B. Application name (optional):** Label indicating the name of the application.<br/>
**C. Section title (optional):** Title used to group navigation elements.<br/>
**D. Icon (optional):** Visual indicator used to enhance the meaning of the navigation link label.<br/>
**E. Navigation link (required):** Label indicating the destination of the link.<br/>
**F. User profile (optional):** Avatar component representing the current user’s account.<br/>
**G. Close button (required):** Icon button used to collapse the navigation drawer.<br/>
**H. Chevron (optional):** Icon indicating the collapsed or expanded state of a multi-level menu item.

## Usage

When to use and when not to use navigation drawer

- When to use: For small screens with many navigation items.<br/><br/>For navigation paired with a [Top app bar](https://design.visa.com/components/top-app-bar).
- When not to use: If your app has a few top-level views, consider a [Tab bar](https://design.visa.com/components/tab-bar).<br/><br/>For larger screen sizes. Use [Vertical navigation](https://design.visa.com/components/vertical-navigation) instead.

## Best practices
- Reference [Application layouts](https://design.visa.com/patterns/application-layouts) for help deciding which navigation component is best for your use case.
- Ensure the order of the navigation items is consistent throughout the application, as changing it may confuse users.
- Ensure text within the navigation panel wraps to a second line instead of truncating to ensure it’s fully visible to users. 
- Include a vertical scroll bar if all navigation items can’t be viewed at once. 
- Consider making the brand mark and/or application name function as a link to the homepage of the experience.
- Follow all guidance found in [Avatar](https://design.visa.com/components/avatar/usage) and [Link](https://design.visa.com/components/link/usage) for implementing a user profile in the navigation panel.

### Section titles and nesting
Section titles refer to static text used to group navigation items under a common category. They can be used with or without nested navigation items, which expand or collapse other navigation items. Both methods group related content and help users navigate easily. Decide which to use based on your use case and design preferences.

         
          #### Section titles
          Section titles group navigation items without nesting them. They’re helpful for grouping items that should always be visible within the menu.  
          <img src="https://design.visa.com/assets/components/navigation-drawer/accordion-chevron-collapse-1.svg" alt="A vertical navigation with tabs grouped under two section titles: 'Account managment' and 'Customer service.'"/>
          - Use section titles to group items that should always be visible in the menu.      
      
         
          #### Nesting
          Nesting items group links within collapsible sections. They’re helpful for more complex apps menus may benefit from limiting the number of links visible at once.         
          <img src="https://design.visa.com/assets/components/navigation-drawer/accordion-chevron-expand-1.svg" alt="A vertical navigation with three tabs nested under an 'Account management' tab and one tab nested under a 'Customer service' tab."/>
          - Consider nesting items in longer navigation menus, as this can help save space and declutter the experience.         
      

### Icon usage
Icons can be used in navigation drawers to make scanning easier and reinforce familiar ideas.
<img src="https://design.visa.com/assets/components/navigation-drawer/vertnav-bp-icons.svg" alt="A vertical navigation bar with level 1 and level 2 section headers. Level 1 section headers have leading icons while level 2 section headers do not have icons."/>
- Ensure icon usage applies to all navigation items within the same hierarchy level. For example, if you use icons for some L1 labels, they should be used in all L1 items. 
- Omit icons for nested items, but if they’re necessary, ensure all items within the nested level has one.

## Behaviors

### Responsive web vs. native mobile applications
Navigation drawers can be used in both responsive web and native mobile applications. Whether its implemented in web or mobile determines the levels of hierarchy it can accommodate. Learn about the differences below.

#### Responsive web applications
In responsive web apps, navigation drawers include multiple levels of hierarchy to reflect the more complex navigation structure.
<img src="https://design.visa.com/assets/components/navigation-drawer/navdrawer-behaviors-web.svg" alt="A drawer in a web layout with one section level opened to the left of the page extending to the page's full height and overlays on top of page content"/>

#### Native mobile applications
For native mobile apps, navigation drawers only have one level of links available. It’s expected that further navigation will be appear within sections of the app as needed.
<img src="https://design.visa.com/assets/components/navigation-drawer/navdrawer-behaviors-mobile.svg" alt="A drawer in a mobile layout with only four tabs to the left of the page extending to the page's full height and overlays on top of page content"/>

### Scrolling
A scroll bar can be used if the navigation is long and doesn’t fit in one view. The navigation items will scroll, while the brand mark, application name, and any items at the bottom remain fixed in position.

<img src="https://design.visa.com/assets/components/navigation-drawer/verticalnav-behaviors-scroll.svg" alt="A navigation drawer with a scrollbar"/>

### Chevron direction
Visually differentiate expanded and collapsed sections using the chevron direction.

         
          #### Collapsed
          Collapsed sections should use the downwards-pointing chevron to indicate collapsed content can be expanded.  
          <img src="https://design.visa.com/assets/components/navigation-drawer/accordion-chevron-collapse-2.svg" alt="Two collapsed tabs labeled 'Account management' and 'Customer service'."/>    
      
       
          #### Expanded
          Expanded sections should use the upwards-pointing chevron to indicate expanded content can be collapsed.          
          <img src="https://design.visa.com/assets/components/navigation-drawer/accordion-chevron-expand-2.svg" alt="Two expanded tabs, labeled 'Account management' and 'Customer service,' to show the tabs nested under each one."/>      
      

## Platform considerations

Navigation drawers are typically only used on small responsive screens, or in native mobile applications. For large screen sizes, use [Horizontal navigation](https://design.visa.com/components/horizontal-navigation/usage) or [Vertical navigation](https://design.visa.com/components/vertical-navigation/usage) instead.

<img src="https://design.visa.com/assets/components/navigation-drawer/notificationtray-platform.svg" alt="A vertical navigation appearing on a mobile layout, obscuring the page content to show an 'Accounts' tab, an active 'Trading' tab, a 'Services' tab, a 'Notifications' tab, and an account profile tab labeled 'Alex Miller'"/>

## Content
- Write all content in sentence case, except for acronyms or proper nouns, like the application name.
- Don’t use punctuation for navigation items.
- Ensure labels match page titles to enhance the user’s understanding of the site’s information hierarchy. 
- Limit labels to a few brief words to prevent unnecessary reflow. 
- Reference [Grammar and punctuation](https://design.visa.com/content/grammar) to learn how to use parallel structure for consistent phrasing.

---

# accessibility

---
title: Pagination
tab_order: 2
description: Set of links used to navigate content that’s split between multiple pages.
meta_description: Find accessibility guidelines for sets of links used to navigate content split between multiple pages.
thumbnail: assets/components/pagination-graphic.svg
---

## Best practices

- Use a navigation landmark by containing the pagination in a `nav` element or an element with `role=&quot;navigation&quot;`  and give the element an aria-label. The landmark allows a user to navigate to this section and see it listed in a page summary.
- Code the pagination controls in an an HTML `ul` so screen readers announce the number of items.
- Ensure the button for the current page has the attribute `aria-current=&quot;page&quot;`.
- Manage the disabled state of the navigational buttons using the `disabled` attribute.
- Give all pagination controls accessible labels, as they are icon buttons.
- Don’t code overflow ellipses as button icons, as they’re not actionable.
- Use the library’s rtl class to ensure the arrows will point the correct direction in an RTL language.

{/* CURSOR AND KEYBOARD */}
## Keyboard controls

  Keyboard actions and their corresponding behaviors for pagination

- Key: Activates link.



---

# index

---
title: Pagination
tab_title: Code
description: Set of links used to navigate content that’s split between multiple pages.
meta_description: Get code for sets of links used to navigate content split between multiple pages.
thumbnail: assets/components/pagination-graphic.svg
categories:
  - selection-controls
  - tables
---

## Component Code Examples: pagination

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the pagination component
const component = parsed.components.find(c => c.name === 'pagination');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `pagination`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Pagination
description: Set of links used to navigate content that's split between multiple pages.
meta_description: Learn how to use sets of links used to navigate content split between multiple pages.
keywords: ["Page navigation", "page toggle", "page numbers", "paging"]
related:
  components:
    - table
  patterns:
    - dynamic-table
tab_order: 1
---

{/* INTRO */}
Pagination is a set of links that allow users to navigate content split into multiple pages. It typically includes navigational controls such as next and previous buttons, as well as direct links to specific pages.<br/><br/>
Also known as: Page navigation, page toggle, page numbers, paging.

## Anatomy
  <img src="https://design.visa.com/assets/components/pagination/pagination-anatomy.svg" alt="Pagination with skip navigation arrows featuring callout A indicating the skip to first page button, sequential navigation arrows featuring callout B indicating the navigate to previous page button, page numbers featuring callout C indicating the page numbers, a selected page number featuring callout D indicating the selected page number, and an ellipsis featuring callout E indicating the overflow pages."/> 
  **A. Skip navigation arrow (optional):** Links allowing users to skip to the first or last page.<br />
  **B. Sequential navigation arrow (required):** Links enabling users to navigate forward or back one page.<br />
  **C. Page numbers (required):** Visible numbers linking to other pages in the collection.<br />
  **D. Selected  page number (required):** Indicator of the current page the user is interacting with.<br />
  **E. Overflow ellipsis (optional):** Non-interactive separator between the start or end page numbers.

## Usage
When to use and when not to use different types of pagination

- Component: To allow users to navigate a collection of content split into multiple pages.
- When to use: For content that can reasonably fit onto one page.

- Component: When space is limited, especially when other ways to filter down results are present.
- When to use: For content split across more than three pages.

 ## Best practices
  - Ensure all page numbers and arrows function as interactive links, except the currently selected page.
  - Use a clear visual indicator to show which page is currently selected.
  - Always allow users to navigate to the first page, last page, back one page, or forward one page using navigation arrows.
  - Display a manageable number of page links, using ellipsis to truncate the list if necessary.

### Default pagination

Default pagination provides a standard way to navigate through large volumes of content or datasets. It's ideal for larger sets of content because it includes more functionality for users to easily move between pages. It typically includes sequential navigational controls, such as next and previous buttons, as well as ellipses and skip navigation controls for users to move to the first and last pages.

<img src="https://design.visa.com/assets/components/pagination/default-pagination.svg" alt="A set of page numbers ranging from one to five, a button for page one hundred, and back and forward arrows."/>

### Slim pagination

Slim pagination is a more compact version of default pagination, designed for scenarios where screen space is limited or when a cleaner, less cluttered interface is desired. It includes only the essential navigational controls, such as next and previous buttons, and may omit direct links to specific pages. Slim pagination is ideal for mobile interfaces or when the total number of pages is relatively small and it’s feasible for the user to navigate one page at a time.

<img src="https://design.visa.com/assets/components/pagination/slim-pagination.svg" alt="A set of page numbers ranging from one to three, back, and forward arrows"/>

### Placement

Pagination is usually centered below an element or at the foot of page content.
 <img src="https://design.visa.com/assets/components/pagination/pagination-bp-placement.svg" alt="A set of page numbers, back, and forward arrows centered below a simplified page layout"/> 
- Place pagination controls in consistent locations throughout an interface.

### Results per page
The “Results per page” feature allows users to control how many items they see on each page of a paginated list. This functionality gives users the flexibility to view more or fewer items per page according to their preferences or needs. It’s particularly useful in scenarios where users may want to adjust the volume of information they are processing, such as in search results, product listings, or data tables.
<img src="https://design.visa.com/assets/components/pagination/pagination-bp-results.svg" alt="A table with a pagination component including an option to choose how many results are shown per page, a set of page numbers, a button for page one hundred, back and forward arrows."/>
- Set a reasonable default number of results per page that balances performance and usability, such as 10 to 20 items, without overwhelming users with too many choices.
- Clearly indicate the current selection of results per page and make it easy for users to change this setting.
- Save the user's preference for the number of results per page, so that they don’t have to re-select it each time they return to the same page or application.
- Ensure that the "Results per page" feature works well on mobile devices, where screen space is limited and users may prefer fewer results per page to avoid excessive scrolling.

## Behaviors
Pagination has a number of expected behaviors depending on the type selected. The guidance below outlines the expected behaviors of default pagination.

### First four pages selected

When users navigate through pages 1–4 in a pagination set, pagination includes one overflow ellipsis symbol representing the pages between the fifth and last page. When page 1 is selected, the arrow buttons to navigate backward should be disabled.
<img src="https://design.visa.com/assets/components/pagination/pagination-behavior-first4.svg" alt="A set of page numbers with the first page selected and back arrows disabled. Ellipses are shown between the 5th and 100th page."/> 

### Middle pages selected

When users select any page other than the first four or last four, pagination includes two overflow ellipsis symbols on either end of three internal page numbers. The selected page should always be the center of the set. The first and last page number should always show and all navigation arrows should be active. 
<img src="https://design.visa.com/assets/components/pagination/pagination-behavior-middle.svg" alt="A set of page numbers with a middle page selected and ellipses between the 1st and 4th number and 6th and 100th."/> 

### Last four pages selected

When users navigate through the last four pages, pagination includes one overflow ellipsis symbol after the number representing page 1. When the last page is selected, the arrow buttons to navigate forward should be disabled.
<img src="https://design.visa.com/assets/components/pagination/pagination-behavior-last4.svg" alt="A set of page numbers with one of the last pages selected and ellipses between the 1st and 96th number."/> 

## Platform considerations

### Web (default)

For web, pagination is shown in a single line with all four navigational arrows and utilizes the behaviors outlined above around overflow. Depending on the use case, navigational arrows can be simplified to the include only sequential controls.
<img src="https://design.visa.com/assets/components/pagination/pagination-platform-web.svg" alt="A set of page numbers, back, forward, jump to end, and jump to beginning arrows"/> 

### Mobile

Mobile screen sizes use a five-control design that limits how many pages are available to users. While pagination for mobile screen sizes is available, it’s generally not recommended for use and isn’t available in mobile native.

<br/><br/>

Consider implementing these common alternatives in place of mobile pagination.

### Infinite scrolling

Infinite scrolling automatically loads new content as a user scrolls through the page, eliminating the need to manually navigate to the next page.

<img src="https://design.visa.com/assets/components/pagination/infinite-scrolling.svg" alt="A mobile screen showing a circular indeterminate progress indicator at the bottom of the screen above the tab to indicate that new content is loading as the user scrolls."/>
- Use for content-heavy applications where continuous exploration is needed.
- Provide visual feedback if needed, such as a loading spinner, to indicate that new content is being loaded.
- Avoid infinite scrolling for content where users might need to find specific information quickly.

### “Load more” button scrolling

“Load more” buttons allow users to manually load content as needed. It provides more control than infinite scrolling, enabling users to decide when they want more information.
<img src="https://design.visa.com/assets/components/pagination/load-more-button.svg" alt="A mobile screen showing a button labeled 'Load more' at the bottom of the screen above the tab to indicate new content can be loaded by pressing the button."/> 
- Place the "load more" button at the bottom of the content list, ensuring it's easily accessible.
- Clearly indicate when new content has been loaded to avoid confusion.
- Consider adding a counter or [Progress](https://design.visa.com/components/progress) indicator to show how much content remains unloaded.


---

# accessibility

---
title: Panel
description: Collapsible or persistent containers used to present supplementary information.
meta_description: Find accessibility guidelines for collapsible or persistent containers used to present supplementary information. 
thumbnail: assets/components/panel-graphic.svg
tab_order: 2
---

## Best practices

<br />
**Note:** Modal panels are implemented as dialogs whereas responsive ones are not. Modal panels have a backdrop scrim and the escape key closes them. 
- Check your panel on different screen sizes to make sure it displays correctly.
- Ensure the content inside is responsive and wraps appropriately. Our components have default widths, but you may need to adjust these. If you make changes, check how the handles fit.
- Ensure modal panels have `aria-modal=&quot;true&quot;`.
- Ensure all panels have `aria-labeledby` pointing to the ID of your panel title if present.
- Ensure all panels have `aria-describedby` pointing to the ID of your panel content if present.

## Keyboard controls

Keyboard actions and their corresponding behaviors for panel

- Key: Prompts the action associated with the focused interactive element.

- Key: Moves keyboard focus to the next focused interactive element.

- Key: Moves keyboard focus backwards to the previous interactive element in the panel.

- Key: Closes the panel.



---

# index

---
title: Panel
tab_title: Code
description: Collapsible or persistent containers used to present supplementary information.
meta_description: Get code for collapsible or persistent containers used to present supplementary information. 
thumbnail: assets/components/panel-graphic.svg
categories:
  - structure-and-layout
---

## Component Code Examples: panel

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the panel component
const component = parsed.components.find(c => c.name === 'panel');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `panel`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Panel
description: Collapsible or persistent containers used to present supplementary information.
meta_description: Learn how to implement collapsible or persistent containers used to present supplementary information. 
keywords: ["(Side/bottom) sheet", "drawer", "tray", "flyout", "side panel"]
related:
  components:
    - dialog
  baseElements:
    - elevation
tab_order: 1
---

Panels are sections of content that provide supplementary information. They’re commonly used for help content and can include follow-up actions using buttons or links.<br/><br/>
Also known as: (Side/bottom) sheet, drawer, tray, flyout, side panel.

{/* ANATOMY */}

## Anatomy

<img src="https://design.visa.com/assets/components/panel/component-anatomy.svg" alt="A panel example featuring callout A indicating the title, callout B indicating the close icon button, callout C indicating the subtitle, and callout D indicating the content area. Another example panel featuring callout E indicating the collapse icon button and callout F indicating the scrim."/>
**A. Title (required):** Brief text describing the panel content.<br />
**B. Close icon button (required):** UI icon button used to close a default panel or exit the full screen view on mobile devices.<br />
**C. Subtitle (optional):** Area displaying content, action buttons, or links.<br/>
**D. Content area (required):** Area displaying content, action buttons, or links.<br/>
**E. Collapse icon button (optional):** Icon button used to collapse or expand the panel.<br/>
**F. Skrim (optional):** Semi-transparent overlay distinguishing the panel from the content underneath.

{/* USAGE */}

## Usage

When to use and when not to use different types of panel

- Component: To provide contextual information prompted by a link, button, or similar interactive element.<br/><br/>
For information related to a specific action or part of the experience.
- When to use: If users may need to access the information repeatedly. Use an expandable panel instead.

- Component: To provide supplementary information the user may want to reference repeatedly.<br/><br/>
For information relating to the whole page or content area.
- When to use: To provide critical guidance, as users may miss important details if they’re hidden in a collapsed panel.

- Component: To divide panel content into categories of information.
- When to use: If you have only a small amount of information or if the information doesn’t naturally divide into categories.

{/* BEST PRACTICES */}
## Best practices
- Use vertical scrolling if there’s overflow content, but avoid horizontal scrolling to maintain readability.
- Ensure all content in the panel relates to the main page content. 
- Ensure panel content is brief and specific. Avoid using panels for long paragraphs or sections of text. 

### Default panels
Default panels provide contextual information prompted by UI controls, such as buttons or links. They can be dismissed using a close icon button. Default panels are best for providing additional details or controls related to a particular step or action within the main page, which users are likely to access once during their workflow, rather than repeatedly.
<img src="https://design.visa.com/assets/components/panel/panel-bp-default.svg" alt="Simplified page layout that shows that the main content area reflows and is responsive to the panel opening"/>

### Expandable panels
Expandable panels provide supplemental information that can be expanded or collapsed at any time during the experience. They’re best for providing information relevant to the entire page, which users may want to reference multiple times throughout their workflow. The expand/collapse button remains available at all times, enabling users to access the information whenever needed.
<img src="https://design.visa.com/assets/components/panel/panel-bp-expandable.svg" alt="Simplified page layout that shows that the main content area reflows as a panel is expanded"/>

### Tabbed panels
Tabbed panels are similar to expandable panels, but include [Tabs](https://design.visa.com/components/tabs/usage) that divide the content into logical groups or categories. They’re best for larger amounts information that may benefit from being broken into categories. Tabbed panels enable users to navigate between different sections of information easily, making it easier to find specific details within a broader context.
<img src="https://design.visa.com/assets/components/panel/panel-bp-tabbed.svg" alt="Simplified page layout that shows that the main content area reflows as a panel with tabs is expanded"/>

{/* BEHAVIORS */}

## Behaviors

###  Modal panels
Modal panels lay on top of the main content using elevation or a semi-transparent skrim overlay. When the panel is open, all other page content is disabled until the panel is dismissed.
<img src="https://design.visa.com/assets/components/panel/panel-bp-modal.svg" alt="Simpified page layout with an overlay and panel above the main content area"/>
- Use modal panels when you need to capture the user’s focus for critical actions or decisions that shouldn’t be distracted by other content on the page.
- Don’t use modal panels if users need to interact with both the panel and the main content simultaneously.

#### Elevation vs. skrim

Modal panels can be indicated using elevation or a semi-transparent skrim overlay. This ensures it’s clear that the page content isn’t interactive when the panel is open. For more information, reference [Elevation](https://design.visa.com/base-elements/elevation).
<img src="https://design.visa.com/assets/components/panel/panel-bp-elevation-skrim.svg" alt="Simpified page layout with a panel using elevation to be above the main content area. Simpified page layout with a skrim overlay and panel above the main content area"/>

###  Responsive panels
Responsive panels push content to the side when open. They don’t limit the interactivity of other elements on the page, so users can interact with the panel and the main page simultaneously.
<img src="https://design.visa.com/assets/components/panel/panel-bp-responsive.svg" alt="Simplified page layout that shows that the main content area reflows and is responsive to the panel opening"/>
- Use responsive panels when users need to interact with both the panel and the main content simultaneously, such as performing tasks that benefit from a side-by-side layout.

  {/* Platform considerations */}

## Platform considerations

### Web
In web platforms, panels fill the full height of the content area and are anchored to the right side of the screen.
<img src="https://design.visa.com/assets/components/panel/button-platform-full.svg" alt="Simplified page layout that shows that the main content area reflows and is responsive to the panel opening"/>

### Mobile
In mobile platforms, panels can either occupy a portion of the screen or take up the full screen, but they always function as [Modal panels](https://design.visa.com/components/panel/usage#modal-panels), meaning functionality is limited on the rest of the screen. If they don't take up the full screen, they should be anchored at the bottom.
<img src="https://design.visa.com/assets/components/panel/notification-tray-platform.svg" alt="Simplified mobile layout that shows a panel occupying a small portion of the bottom of the screen"/>
- Consider using a [Dialog](https://design.visa.com/components/dialog) instead to present options or actions. This provides more ergonomic and mobile-friendly interaction.
- Ensure mobile panels always include a close icon button.

  {/* Content */}

## Content
- Use simple language—avoid abbreviations or jargon. 
- Use sentence case, except for proper nouns or acronyms.

### Panel headings
- Use short, concise content that describes the panel content clearly. 
- Only use punctuation when labels are phrased as questions, such as “How do I edit my billing information?”

### Panel content
- Use complete sentences and proper punctuation within each section or panel.
- Keep the content within each panel concise and to the point. 
- Avoid unnecessary details or complex language. 
- Provide users with the answers they need as quickly and efficiently as possible.
- If content within the panel is becoming too lengthy, it may be a sign that the information should be presented in a different way, such as being broken down further, moved to a separate page, or even represented visually.


---

# accessibility

---
title: Progress
description: Visual representations of the status of a system process.
meta_description: Find accessibility guidelines for visual representations of the status of a system process.
thumbnail: assets/components/progress-graphic.svg
tab_order: 2
---

## Best practices

<br/>
Implementing progress indicator components for people who rely on screen readers takes thought and is less intuitive than for most of the other components. There is not a one-size-fits all solution.
- Use `alert` , `role=&quot;status&quot;`, or `aria-live` to announce the start and end of a progress indicator. Alerts, status, and aria-live interrupt the user, even when set to “polite”, and could be especially disruptive with progress indicators.
- Set timed announcements, such as every 30 seconds or minute, for longer progress indicators.
- Place the progress element near the control prompting it in the DOM so screen reader users can find it easily.
- Don’t give indeterminate progress indicators a `role=&quot;progressbar&quot;`, as they only communicate a process is happening and navigating to them doesn’t yield any additional information.
- Use labels and aria labeling attributes with progress indicators as needed. Alerts and live-areas need to be handled with finesse when it comes to their timing.
- Don’t place alerts or live areas inside progress elements, as any content contained in a progress element or an element with `role=&quot;progressbar&quot;` will be given an implicit `role=&quot;presentation&quot;` by the browser and not announced.
- Check the linear progress indicator’s native `progress` component. It uses a value attribute which often needs to be converted to a percentage by the developer.
- Check the circular progress indicator’s div with the `role=&quot;progressbar&quot;`. It must have an `aria-valuenow` attribute which is updated by the developer.

### Determinate vs indeterminate progress behaviors

#### Determinate

- Linear determinate indicators have a `progress` element with a value attribute.
- Circular determinate indicators have `role=&quot;progressbar&quot;` and `aria-valuenow` attributes.
- Ensure determinate indicators are located in the DOM near the control that prompted the process. While they’re not in the page tab order, they can be reached with the keyboard when a screen reader is on.
- Ensure progress values are announced only in certain situations, and then in a deliberately timed manner.

#### Indeterminate

- Ensure indeterminate indicators don’t have roles.
- Ensure they’re announced, although they don’t need to be accessible in the DOM.

#### Motion sensitivity

- Consider implementing a way to pause animations for indeterminate progress indicators, especially if they’re displayed for a long time.   



---

# index

---
title: Progress
tab_title: Code
description: Visual representations of the status of a system process.
meta_description: Get code for visual representations of the status of a system process.
thumbnail: assets/components/progress-graphic.svg
categories:
  - feedback-and-status
---

## Component Code Examples: progress

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the progress component
const component = parsed.components.find(c => c.name === 'progress');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `progress`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Progress
description: Visual representations of the status of a system process. 
meta_description: Learn how to use visual representations of the status of a system process.
keywords: ["Progress indicator", "progress bar", "loading indicator", "progress ring", "spinner", "loader", "progress loader", "activity indicator", "ProgressView(iOS)", "ProgressBar(Android)"]
related:
  patterns:
    - forms
    - wizard
tab_order: 1
---

Progress components are non-interactive elements that visually indicate the progress of a task or function.<br/><br/>
Also known as: Progress indicator, progress bar, loading indicator, progress ring, spinner, loader, progress loader, activity indicator, ProgressView(iOS), ProgressBar(Android).

## Anatomy

<img src="https://design.visa.com/assets/components/progress/progress-anatomy.svg" alt="An example linear progress indicator featuring callout A indicating the progress indicator, 'Filename.jpg' featuring callout B indicating the label, and '15%' featuring callout C indicating the completion status."/>

**A. Progress indicator (required):** Animated fill indicating the function is in progress.<br/>
**B. Label (optional):** Label indicating what’s in progress, such as a file name.<br/>
**C. Status (optional):** Label indicating how much process has been completed for determinate indicators.

## Usage

When to use and when not to use different types of progress

- Component: When space is limited.

- Component: When the design has sufficient space.

- Component: For a more detailed progress indicator, such as in dashboards or control panels.<br/><br/>**Note:** Progress gauges are only available as determinate indicators. Learn more below.

## Best practices
- Avoid using progress components for very lengthy load times, as users may perceive that the app is slow or frozen. 
- Only use determinate progress indicators if the exact amount of completion is known. Learn more below. 

### Determinate progress

Determinate progress indicators display how long a process will take. They include an exact percentage or fraction indicating how much progress has been made.

<img src="https://design.visa.com/assets/components/progress/progress-bp-determinate.svg" alt="Determinate progress indicators showing how long the process will take"/>
- Only use determinate indicators when the amount of completion is known, as estimating can be misleading or cause frustration.

### Indeterminate progress

Indeterminate progress indicators display unknown wait times. Indeterminate progress indicators may turn into determinate progress when more information is available.

<img src="https://design.visa.com/assets/components/progress/progress-bp-indeterminate.svg" alt="Indeterminate progress indicators showing an unknown wait time"/>
- Use indeterminate indicators when the amount of progress is unknown or not important.

### Placement

In general, progress indicators should be placed near the function they represent. o show that an entire page or app is loading, place a linear indicator at the top of the page or just below the navigation bar.

<img src="https://design.visa.com/assets/components/progress/progress-placement.svg" alt="Progress bar shown anchored to horizontal navigation bar"/>
- Consider using skeleton loading to further indicate that loading is in progress.

## Content
- Use plain language without abbreviations or jargon. 
- Annotate the percentage completed in determinate progress components.


---

# accessibility

---
title: Radio
description: Interactive elements that allow users to select a single option from a list. 
meta_description: Find accessibility guidelines for interactive elements that allow users to select a single option from a list.
thumbnail: assets/components/radio-graphic.svg
tab_order: 2
---

## Best practices

- Ensure all the radio buttons in a group have the same `name` attribute.
- Put the radio buttons inside a `fieldset`, and give it a `legend`.
- Ensure each radio button has an `id` associating it with its label. Be sure to associate additional text and error messages to its relevant radio input or fieldset. Reference [the coded examples.](https://design.visa.com/components/radio)<!-- aria-label="radio code examples" -->

## Keyboard controls
Keyboard behaviors treat radio buttons as a group. Tabbing into the group focuses the first radio. Tabbing a second time does not go to the second radio, it moves to the next focusable element after the radio group. Placing focus on a radio button automatically selects in. Use the following focus order to ensure radio groups are accessible and predictable:
- Ensure focus is placed on the currently selected option upon tabbing into the group.
- If all options are unselected, ensure focus is placed on the first radio button in the group.
- If the group is in an error state, focus is moved to the first radio button, and the whole fieldset is given the error (red) style.

Keyboard actions and their corresponding behaviors for radio

- Key: Moves the focus and selection to the next radio in the group and unselects the previously focused one. Focus moves in a circular rotation within the group, so progressing past the last option returns focus to the first in the group.

- Key: Moves to the next focusable element outside the radio group.

- Key: Moves to the previous focusable element outside the radio group.

- Key: Selects the focused element if it’s not already selected. This allows the user to select an item without additional keyboard steps.



---

# index

---
title: Radio
tab_title: Code
description: Interactive elements that allow users to select a single option from a list.
meta_description: Get code for interactive elements that allow users to select a single option from a list.
thumbnail: assets/components/radio-graphic.svg
categories:
  - selection-controls
---

## Component Code Examples: radio

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the radio component
const component = parsed.components.find(c => c.name === 'radio');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `radio`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Radio
description: Interactive elements that allow users to select a single option from a list. 
meta_description: Learn how to use interactive elements that allow users to select a single option from a list.
keywords: ["Radio buttons", "radio selections", "RadioGroup", "RadioButton (Android)"]
related:
  components:
    - checkbox
    - select
    - listbox
  patterns:
    - forms
tab_order: 1
---

Radios buttons present a short list of options where the user must select one. They’re commonly used in forms, user preference selections, surveys, or any scenario where a single selection from multiple options is required.
<br />
Also known as: Radio buttons, radio selections. RadioGroup, RadioButton (Android).

## Anatomy
<img src="https://design.visa.com/assets/components/radio/radio-anatomy.svg" alt="A single radio button with the radio button featured with callout A, the label featured with callout B, and the description featured with callout C. Another radio group with the radio buttons group featured with callout D and the group label featured with callout E."/>
**A. Radio button (required):** Interactive element enabling users to select an option. <br/> 
**B. Option label (required):** Brief text describing the radio option. <br/> 
**C. Description (optional):** Brief message detailing important information about the option. <br/>
**D. Radio button group (optional):** Short list of radio buttons presented in a group. <br/>
**E. Group label (required):** Brief description of options available for selection. <br/>

## Usage
When to use and when not to use different types of radios

- Component: Using one radio button alone is not a common use case.
- When to use: To present one option available for selection. Use a [Checkbox](https://design.visa.com/components/checkbox) instead.

- Component: To present a short list of options where the user must select one.
- When to use: If users can select multiple options from a short list. Use a [Checkbox group](https://design.visa.com/components/checkbox/usage#checkbox-groups) instead. <br/><br/>For long lists where all options can't be viewed at once or require scrolling. Use [Select native](https://design.visa.com/components/select) or a [Single-select listbox](https://design.visa.com/components/listbox) instead. <br/><br/>For long lists when users would benefit from entering text to filter or search the list options. Use a [Combobox](https://design.visa.com/components/combobox) instead. <br/><br/>To present a list of actions. Use a [Dropdown menu](https://design.visa.com/components/dropdown-menu) instead.

- Component: Using one radio button panel alone is not a common use case.
- When to use: To present one option available for selection. Use a [Checkbox](https://design.visa.com/components/checkbox) instead.

- Component: To present a short list of options where the user must select one. <br/><br/>To provide an increased touch area.
- When to use: If there is limited space. Use a Radio button group instead.

## Best practices
- Ensure radio buttons appear visually different when selected and unselected by using an appropriate fill color.
- Ensure users can select anywhere within the radio button or associated option label to choose an option.
- List options in a logical order, either alphabetically or according to the most common or likely selection.
- Avoid using a horizontal layout for radio button groups and panel groups, as vertical layouts are easier to scan and more adaptable for small screens. 

### Radio button panels
Radio button panels are an alternative to default radio buttons that include a rectangular border around the button and option label. They can be used to draw attention to the radio group or provide an increased touch area on small screens. 
- Ensure users can select anywhere within the radio button, label, or panel to choose an option. 

### Label size for panel groups
Labels for radio panel groups are available in two sizes. Use whichever is appropriate depending on your use case and the overall hierarchy of your experience. 

#### Default

The default option is the UI label font size and matches the text in option descriptions.
<img src="https://design.visa.com/assets/components/radio/radio-size-default.svg" alt="A radion button panel group with the label size in default."/>
- Use the default size to reduce visual weight for users when multiple radio button panel groups are used together.

#### Large

The large UI label size is an alternative option that can be used to draw attention to the checkbox panel group label. 
<img src="https://design.visa.com/assets/components/radio/radio-size-large.svg" alt="A radio button panel group with the label size in large."/>
- Use the large size to draw attention to a standalone radio panel group.

### Hidden labels
Radio button groups and panel groups should always include a group label. However, there are some cases where hiding the group label can provide design flexibility or space for additional context. If the group label within the component build is hidden, include a label elsewhere on the screen as well as within the code for accessibility.
<img src="https://design.visa.com/assets/components/radio/radio-hidden-labels.svg" alt="A radio button group in a form with its label hidden. The radio button group is within a question on the form that provides context about the radio button group."/>
- Always include a group label somewhere on the screen if you choose to omit it from the component build. 
- Always include the group label within the code to ensure screen readers users have full context. 

### Optional vs. required labels
Always ensure required fields are clearly labeled. While this may seem repetitive, it helps users scan for necessary information and reduces errors. There are two methods for labeling required fields based on your use case. Whichever method you select, use it consistently across your experiences. <br/><br/>
**Note:** Previous VPDS guidance recommended only marking optional fields. Our guidance has been updated to reflect current [Nielsen Norman Group](https://www.nngroup.com/articles/required-fields/)<!-- aria-label="Nielsen Norman Group (opens in a new tab)" --> recommendations. Learn more about optional vs. required labels in [Forms](https://design.visa.com/patterns/forms/#optional-vs-required-labels).

                    
              ### “Required” in the label (preferred method)
              
              <Typography variant="body-2">Including “required” within the label ensures it’s easy to find, particularly when instructions at the top might not be visible while scrolling. This method bolsters accessibility for both sighted and non-sighted users. </Typography>  
              
                 <img src="https://design.visa.com/assets/components/radio/radio-mark-required.svg" alt="A radio button group with its label marked as required"/>
              
              - Mark all fields that are required. This ensures you’re as explicit and transparent as possible.
              - Include “(required)” in field label with a space between the last word and the first parenthesis. 
                 
          
                    
              ### Asterisk in the label (alternative method)
              <Typography variant="body-2">
              Asterisks are commonly used to indicate required fields. The main advantage to using this method is that it doesn’t take up much space, helps users along a common edge, and can be used in addition to formatting hints in the label. 
              </Typography>
              
               <img src="https://design.visa.com/assets/components/radio/radio-asterisk.svg" alt="A checkbox with an asterisk in the label "/>
              
                - Always include a legend or key at the top of the content area noting that the asterisk indicates a required field.
                - Place the asterisk at the beginning of the label with a space between the symbol and the first word.
          
    

### When required is implied
Although it's usually recommended to label required fields, there are cases where it’s implied that the field is required. This is common when there’s a one or two fields fundamental to completing of a task, like the username and password fields on a login screen. In these cases, marking the fields required isn’t necessary but can add additional clarity.

### Labeling optional fields
It’s not generally necessary to mark which fields are optional. While doing so can support clarity, it also adds unnecessary visual noise. Whatever you choose, apply the choice consistently to avoid confusion.

### Including "None" as an option
Radio button groups require a single option to be selected. Once a radio button is selected, it can only be unselected by choosing another option in the group. 
- Include “None” as an option if users are allowed to omit a selection. This functions as an “unselect” option if users accidentally choose an option they don’t want or wish to omit a selection altogether.

### Default selections
In general, radio buttons should be unselected by default to give users full control over their choices. The main exception is when the selection indicates a default or system setting. 
- Avoid default selections when possible to encourage users to make an active choice. Including default selections can make it easier for users to skip fields and may result in choices they don’t agree with. 

## Behaviors
### Single-selection
Radio buttons enforce a single selection from a short list. Selecting one option automatically deselects all others. Once a radio button is selected, it can’t be unselected by selecting it again. Another option must be selected to change the current one.

<img src="https://design.visa.com/assets/components/radio/radio-behaviors-mutually-exclusive.svg" alt="A radio button group with the first option selected. When users select the second option then the first option is unselected."/>

## Content
- Always use sentence case except for proper nouns or acronyms.
- Use plain language and avoid abbreviations or jargon.
- Visit [Content](https://design.visa.com/content) for additional guidance on crafting content within apps and experiences. 

### Description
- Use full sentences with proper punctuation.
- Limit descriptions to 80 characters or 20 words including spaces.

### Labels
- Don’t use punctuation.
- Limit labels to three words or fewer unless referencing proper nouns, such as product names. 
- Ensure group labels accurately summarize the options available for selection.
- Use [Parallel structure](https://design.visa.com/content/grammar#parallel-structure) for labels across your experience, either starting with verbs such as “Select a notification preference” or nouns such as “Notification preferences”.

## Platform considerations
Radio buttons are available in mobile and web and should be implemented similarly on both platforms.
- Use radio button panels to provide a larger touch area when necessary. 
- Use default radio buttons to save space and prevent user overload, especially when there are many radio button groups used together in a form.
<img src="https://design.visa.com/assets/components/radio/radio-mobile.svg" alt="A radio button panel group and radio button group displayed in a mobile layout."/>


---

# accessibility

---
title: Section message
description: Section-level messages about the status of a page or action.
meta_description: Find accessibility guidelines for section-level messages about the status of a page or action.
thumbnail: assets/components/section-message-graphic.svg
tab_order: 2
---

## Best practices

<br />
**Note:** Section messages shouldn’t rely on visual cues such as color or icons to communicate to users. Ensure there is additional text to relay  information. Some of our libraries have default values for message type labels such as “success”, “warning”, and “error” but you may want to use custom labels, especially if your app is multilingual.

- Ensure section messages use headings in the correct hierarchical order without skipping levels. Headings can be styled to look like a different level. See your preferred library for more information on Typography.
- Use attributes to announce content to screen readers if you need to show a section message dynamically after the page loads.  Select which attributes to use based on the message purpose and content.`role` with a value of `status` or `alert`, `aria-live`, and `aria-atomic` are useful.
- Ensure screen readers announce the messages at the desired time.

## Keyboard controls
**Note:** Section messages are comprised of other elements which use standard keyboard actions. Activating the Escape key does not close the section message, as that might disrupt what the user is doing by closing something else.

Keyboard actions and their corresponding behaviors for section message

- Key: Prompts the action associated with the focused interactive element.

- Key: Moves focus to the next focusable element.

- Key: Moves keyboard focus backwards to the previous interactive element in the banner.



---

# index

---
title: Section message
tab_title: Code
description: Section-level messages about the status of a page or action.
meta_description: Get code for section-level messages about the status of a page or action.
thumbnail: assets/components/section-message-graphic.svg
categories:
  - feedback-and-status
---

## Component Code Examples: section-message

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the section-message component
const component = parsed.components.find(c => c.name === 'section-message');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `section-message`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples


---

# usage

---
title: Section message
description: Section-level messages about the status of a page or action. 
meta_description: Learn how to use section-level messages about the status of a page or action.
keywords: ["Informational notice", "inline message", "alert", "callout", "message bar", "notification"]
related:
  components:
    - banner
    - flag
  patterns:
    - feedback-and-status
  content:
    - messaging
tab_order: 1
---

Section messages offer feedback that is specific to a user's actions or the status of a particular page section. Rather than applying to the whole site or application, these messages are unique to individual sections and appear near the associated content. They remain visible until the user either engages more or decides to close them. 
<br />
Also known as: Informational notice, inline message, alert, callout, message bar, notification.

## Anatomy

<img src="https://design.visa.com/assets/components/section-message/sectionmessage-anatomy.svg" alt="A section message consisting of an icon featured with callout A, a title featured with callout B, a message featured with callout C, a close icon button featured with callout D, and a button featured with callout E."/>

**A. Icon (required):** Visual indicator communicating the urgency of the section message. <br/> **B. Title (optional):** Brief text summarizing the purpose of the section message. <br/> **C. Message (required):** Descriptive message detailing important contextual information. <br/> **D. Close icon button (optional):** Icon button used as a close button alternative that allows users to manually dismiss the message. <br/> **E. Button and link (optional):** Text button or link that prompts an action or providing access to resources relevant to the message.

## Usage

When to use and when not to use different types of section messages

- Component: For low-priority status updates contextually relevant to the user’s current workflow.
- When to use: For informational messages that are of high enough priority to disrupt the user's workflow, even though they may not require immediate action. Use a [Dialog](https://design.visa.com/components/dialog/usage) instead. <br/><br/> For low-priority, system-level messages. Use a [Banner](https://design.visa.com/components/banner/usage) instead. <br/><br/> For low-priority feedback or status updates that don’t require user action or attention. Use a [Flag](https://design.visa.com/components/flag/usage) instead.

- Component: Success section messages are not a common use case.
- When to use: For system- or section-level success, including on-page event confirmations. Use a [Flag](https://design.visa.com/components/flag/usage) instead. <br/><br/> If the user is taken to a success page on submit. Don’t use a messaging component in this case.

- Component: For medium-priority feedback warning of potential issues within the section. This is the most frequent use case.
- When to use: For high-priority warnings that must be fixed or acknowledged before continuing. Use a [Dialog](https://design.visa.com/components/dialog/usage) instead. <br/><br/> For medium-priority, system-level  messages that require attention but not disruption. Use a [Banner](https://design.visa.com/components/banner/usage) instead. <br/><br/> For low-priority warnings that don’t require user action or attention. Use a [Flag](https://design.visa.com/components/flag/usage) instead.

- Component: For high-priority feedback alerting that errors or issues have occurred within the section and must be fixed.
- When to use: For high-priority errors that must be fixed before continuing. Use a [Dialog](https://design.visa.com/components/dialog/usage) instead. <br/><br/> For high priority, system-level errors that require attention. Use a [Banner](https://design.visa.com/components/banner/usage) instead.

- Component: For low-priority feedback notifying users of tips or more information.
- When to use: For high-priority errors or feedback. Use section messages that denote more critical status instead.

## Best practices

  - Ensure section messages do not block interactive elements or content within the page section.<br/>
  - Visit [Button](https://design.visa.com/components/button/usage) to learn about best practices for alignment, order, and language for calls to action.<br/>
  - Visit [Feedback and status](https://design.visa.com/patterns/feedback-and-status) to learn how to use messaging components, understand their level of disruption, and choose the appropriate messaging component for your context.

## Behaviors

### Dismissal

In general, users should be allowed to dismiss section messages using a close icon button or text button. Section messages should also dismiss when users complete an associated action, such as correcting an error. Avoid using timed auto-dismissal for section messages, as they may disappear before screen readers finish announcing the text.

## Placement
Section messages should be placed at the top of the sections they pertain to, either above or below the section title. Consider screen reader order when choosing a placement method. Whichever you choose, implement it consistently across your experience. 

## Content

- Learn how to craft content for messaging components, like section messages, visit [Messaging](https://design.visa.com/content/messaging).
- Follow guidelines for [Link](https://design.visa.com/components/link/usage) and [Button](https://design.visa.com/components/button/usage) components when labeling actions and destinations within section messages.


---

# accessibility

---
title: Select (native)
description: HTML element that allows users to select one option from a dropdown menu.
meta_description: Find accessibility guidelines for HTML elements that allow users to select one option from a dropdown menu.
thumbnail: assets/components/select-graphic.svg
tab_order: 2
---

## Best practices

<br/>
**Note:** VPDS uses native HTML select elements. As a result, developers have a limited amount of control over how these elements appear and behave. The menu is styled by the browser and will differ between them.
- Ensure each select has an ID associating it with its label. 
- Always show the full text of longer options in the expanded menu view. Only truncate text in the field after a selection is made.
- Be sure to associate additional text and error messages to the select or its fieldset. Reference the code for more. 

## Keyboard controls

Keyboard actions and their corresponding behaviors for selects

- Key: Moves the focus to the first menu item.

- Key: Moves the focus to the last menu item.

- Key: Expands the menu.

- Key: Moves the focus and selection to the next menu item. Selects the next option when the menu is not expanded.

- Key: Opens the menu if the menu is closed. When the menu is open, selects/activates the menu item in focus and closes the menu.

- Key: Closes the menu, setting the focus back on the button or element the menu was activated from. If the focus or hover was set to a different menu item, closing the menu with Esc will not update the selection.

	


---

# index

---
title: Select (native)
side_nav_title: Select (native)
side_nav_aria_label: Select (native)
tab_title: Code
description: HTML element that allows users to select one option from a dropdown menu.
meta_description: Get code for HTML elements that allow users to select one option from a dropdown menu.
thumbnail: assets/components/select-graphic.svg
categories:
  - actions
  - selection-controls
---

## Component Code Examples: select

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the select component
const component = parsed.components.find(c => c.name === 'select');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `select`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Select (native)
description: HTML element that allows users to select one option from a dropdown menu.
meta_description: Learn how to use HTML elements that allow users to select one option from a dropdown menu.
keywords: ["Select menu", "dropdown", "select input", "menu", "UIPickerView (iOS)", "Spinner (Android)", "Menu (Android)", "MenuItem (Android)"]
related:
  components:
    - dropdown-menu
    - listbox
    - radio
tab_order: 1
---

Select allows users to select one option from a list. They often appear in forms to save space and provide a clear, concise selection process.
<br />
Also known as: Select menu, dropdown, select input, menu, UIPickerView (iOS), Spinner (Android), Menu (Android), MenuItem (Android).

## Anatomy

<img src="https://design.visa.com/assets/components/select/select-native-anatomy.svg" alt="A native select with a required label featured with callout A, a field featured with callout B, and a chevron icon button featured with callout C. Another native select with an expanded menu featured with callout D and options featured with callout E."/>
**A. Label (required):** Text summarizing the options available for selection.<br/>
**B. Field (required):** Field displaying an empty state or the selected option.<br/>
**C. Chevron icon button (required):** UI icon button that expands or collapses menu.<br/>
**D. Menu (required):** Container displaying list of options that includes scroll bar as needed.<br/>
**E. Option (required):** Selectable text representing a single option.

## Usage

When to use and when not to use a select

- Component: To present a list of options when the user can only select one.<br/><br/>
            For long lists where all options can't be viewed at once or require scrolling.<br/><br/>
            If space is limited and displaying options in a collapsible menu would help.
- When to use: If users can select multiple options. Use [Multiselect](https://design.visa.com/components/multiselect/usage) instead.<br/><br/>
            For short lists where all options can be viewed without scrolling. Use a [Radio button group](https://design.visa.com/components/radio/usage) instead.<br/><br/>
            For long lists where users would benefit from entering text to filter or search the list options. Use a  [Combobox](https://design.visa.com/components/combobox/usage) instead.<br/><br/>
            To present a list of actions. Use a [Dropdown menu](https://design.visa.com/components/dropdown-menu/usage) instead.

## Best practices
- List options in a logical order, either alphabetically or according to the most common or likely selection.
- Follow the default appearance and interaction of the select component on different browsers.
- Limit the number of options to avoid overwhelming users. Keep the options simple and straightforward.

### Select vs. dropdown
Select and [Dropdown menus](https://design.visa.com/components/dropdown-menu/usage) seem similar but have different functions and code. The select appearance will be determined by the browser, while the dropdown list can be styled as needed.

         
          #### Select

            Selects present a list of options from which the users can select only one option. They’re typically used in forms to help users choose an option from the list and submit data. 
            <img src="https://design.visa.com/assets/components/select/input-mark-required.svg" alt="A native select component with the menu expanded"/>
            - Use the select component when users need to choose a single option from a list, especially when the choice is part of a form submission process.
      
         
          #### Dropdown

            Dropdowns present a list of options that users can select one or several options from that list. However, the options are used for taking an action, filtering, or sorting existing content.
          <img src="https://design.visa.com/assets/components/select/input-asterisk.svg" alt="A dropdown menu component with the menu expanded"/>
          - Use the dropdown component when users need to select one or multiple actions from a list, particularly when the actions involve sorting or filtering existing content.      
      

### Appearance
Native selects are difficult to style consistently across different browsers as they leverage the native appearance. Each browser will render the menu differently, so it's important to test the select component on various devices.

<img src="https://design.visa.com/assets/components/select/select-menu_native.svg" alt="Two native select components, one from Safari and another one from Chrome"/>

         
          #### Collapsed

            The chevron should point down when the menu is collapsed.
            <img src="https://design.visa.com/assets/components/select/combobox-behaviors-chevron_include.svg" alt="A native select component with the menu collapsed"/>
            - Allow users to expand the menu by selecting anywhere in the field, not just the chevron icon.
      
         
          #### Expanded

            The chevron should point up when the menu is expanded.
          <img src="https://design.visa.com/assets/components/select/combobox-behaviors-chevron_include-1.svg" alt="A native select component with the menu expanded"/>
          - Allow users to collapse the menu by removing focus from the field, not just by selecting the chevron icon.      
      

### Optional vs. required labels
Always ensure required fields are clearly labeled. While this may seem repetitive, it helps users scan for necessary information and reduces errors. There are two methods for labeling required fields based on your use case. Whichever method you select, use it consistently across your experiences. <br/><br/>
**Note:** Previous VPDS guidance recommended only marking optional fields. Our guidance has been updated to reflect current [Nielsen Norman Group](https://www.nngroup.com/articles/required-fields/)<!-- aria-label="Nielsen Norman Group (opens in a new tab)" --> recommendations. Learn more about optional vs. required labels in [Forms](https://design.visa.com/patterns/forms/#optional-vs-required-labels).

                    
              ### “Required” in the label (preferred method)
              
              <Typography variant="body-2">Including “required” within the label ensures it’s easy to find, particularly when instructions at the top might not be visible while scrolling. This method bolsters accessibility for both sighted and non-sighted users. </Typography>  
              
              <img src="https://design.visa.com/assets/components/select/input-mark-required-1.svg" alt="A collapsed native select component with 'required' in the label"/>
              
              - Mark all fields that are required. This ensures you’re as explicit and transparent as possible.
              - Include “(required)” in field label with a space between the last word and the first parenthesis. 
                 
          
                    
              ### Asterisk in the label (alternative method)
              <Typography variant="body-2">
              Asterisks are commonly used to indicate required fields. The main advantage to using this method is that it doesn’t take up much space, helps users along a common edge, and can be used in addition to formatting hints in the label. 
              </Typography>
              
               <img src="https://design.visa.com/assets/components/select/select-asterisk.svg" alt="A collapsed native select component with an asterisk in the label indicating a required field"/>
              
                - Always include a legend or key at the top of the content area noting that the asterisk indicates a required field.
                - Place the asterisk at the beginning of the label with a space between the symbol and the first word.
          
    

### When required is implied
Although it's usually recommended to label required fields, there are cases where it’s implied that the field is required. This is common when there’s a one or two fields fundamental to completing of a task, like the username and password fields on a login screen. In these cases, marking the fields required isn’t necessary but can add additional clarity.

### Labeling optional fields
It’s not generally necessary to mark which fields are optional. While doing so can support clarity, it also adds unnecessary visual noise. Whatever you choose, apply the choice consistently to avoid confusion.

## Behaviors

### Pre-selected options
Some browsers require the native select component to have an option selected by default. This is typically the first option in the list. To ensure users don’t mistake this preselected option as their own choice, developers can use one of two methods.<br/><br/>
**Note:** Always work with your development team to ensure that the implementation of the select component design aligns with this default behavior.

         
          #### First option empty

            An empty option can be included as the first option. This option will be selected by default but does not represent a valid selection, prompting the user to make a choice. If the field is required, selecting the empty option and attempting to submit will result in an error. However, if the field is not required, it will not prompt an error if left empty.
            <img src="https://design.visa.com/assets/components/select/input-mark-required.svg" alt="A native select menu expanded with the first option empty"/>
            - Leave field empty, both visually and programatically.
            - Use descriptive labels to guide users to make a selection.
            - Use error messages to guide users when a valid option is not selected. 
      
         
          #### First option disabled

            The first option can be set as 'disabled' and 'selected' simultaneously, acting as a pseudo-placeholder. This option will be selected by default, but the user will not be able to choose it, encouraging them to select a different option. Once a user changes the selection, they cannot select the empty option anymore unless they reload the form/page.
          <img src="https://design.visa.com/assets/components/select/input-asterisk.svg" alt="A native select menu expanded with the first option disabled"/>
          - Use a descriptive text for the first, disabled option such as "Select an option" or “Choose an option.”
          - Ensure the option is visually distinct from the rest of the options using disabled styling.    
      

### Selection method
Users can select an option from the menu using the following method, which aims to simplify the process and prevent accidental selections.
<br />
**Note:** If you want to use an instant selection method, build your own using our low-level components and your own logic. Product teams using this method are responsible for ensuring accessibility standards and practices are met. 

#### Select and confirm

Select and confirm requires users to confirm their choice before it's displayed in the field. When the user places focus on an option within the menu, it won't appear as the selected value in the field until the user selects the option they want on click or using the enter key.

<img src="https://design.visa.com/assets/components/select/select-native-behaviors-menu-expand.svg" alt="A native select menu expanded with an option focused and another native select component showing the selected option"/>
- Ensure the selected option is not displayed until the user confirms their choice. This prevents accidental selection and gives users the opportunity to change their mind      before submission.

## Content
- Always use sentence case except for proper nouns or acronyms.
- Use plain language and avoid abbreviations or jargon.
- Reference [Content](https://design.visa.com/content) for additional guidance on crafting content within apps and experiences. 
- Avoid using unnecessary articles like “the” or “an”, unless they’re included in the proper name of a product or service.

### Labels
- Limit field labels to a maximum of three to five words.
- Be consistent when using plural language or “(s)” in field labels. For example, use “Select card type”, “Select card types”, or “Select card type(s)” consistently. If using “(s)”, use the asterisk method to label required fields instead of “(required)” within parenthesis to keep concise. 
- Use parallel structure across field labels, using either nouns like "Services" or verbs like "Select a service". Learn more about parallel structure in [Grammar and punctuation](https://design.visa.com/content/grammar#parallel-structure).

### Option labels
- Limit option labels to three words or fewer unless referencing proper nouns, such as product names. 
- Avoid using unnecessary articles like “the” or “an”, unless they’re included in the proper name of a product or service.  
- Consistently order labels across experiences based on logical sequence, either alphabetically or by importance.

### Inline messages
- Use full sentences with proper punctuation. 
- Limit descriptions to 80 characters or 20 words including spaces.
- Provide useful information such as why a field is required (if not obvious) without being technical.
- Give an example or specific syntax or values for inputs to help avoid errors.

#### Inline error message

- Use inline error messages to draw attention and to errors without causing frustration.
- Provide clear, prescriptive guidance on correcting the error. Avoid redirecting users to another page to fix it. 
- Communicate whether the problem can occur again and offer an alternative backup solution in case it does.


---

# index

---
title: Slider
tab_title: Usage
description: Control that allows users to make a selection along a range.
meta_description: Learn how to use controls that allow users to make a selection along a range.
thumbnail: assets/components/slider-graphic.svg
keywords: ["Range selector", "range slider", "trackbar", "scale", "control slider", "value selector", "UISlider (iOS)", "SeekBar (Android)"]
related:
  components:
    - checkbox
    - radio
categories:
  - actions
  - selection-controls
---

Sliders are interactive controls enabling users to set or select a value along a range. They’re typically used in settings or configurations. 
<br/>
Also known as: Range selector, range slider, trackbar, scale, control slider, value selector, UISlider (iOS), SeekBar (Android).

## Anatomy

<img src="https://design.visa.com/assets/components/slider/slider-anatomy.svg" alt="A slider example with the label 'Brightness' featured with callout A indicating the required label, a rail featured with callout B, a tooltip '100' featured with callout C, and a switch circle featured with callout D."/>

**A. Label (required):** Text indicating the purpose of the slider. <br/>
**B. Tooltip (optional):** Tooltip component used to indicate the currently selected value. <br/>
**C. Rail (required):** Background element representing the available range for the slider.<br/>
**D. Min/max value (optional):** Text or icon indicating the range of available values.<br/>
**E. Switch circle (required):** Interactive element used to set the value along the rail.

## Usage

When to use and when not to use a select

- When to use: To switch between content views. Use a [toggle button](https://design.visa.com/components/toggle-button/usage) instead. <br/><br/>
            In place of a [checkbox](https://design.visa.com/components/checkbox/usage) or [radio button](https://design.visa.com/components/radio/usage).

## Best practices

- Position the lower value on the left and the higher on the right for left-to-right languages.
- Consider using a [checkbox](https://design.visa.com/components/checkbox/usage) group or [radio](https://design.visa.com/components/radio/usage) if there are only a handful of options, as they can be easier to interact with. 

### Discrete vs. continuous sliders

Sliders can be discrete or continuous, which refers to how the values behave when the slider is adjusted. Learn about each option below.

#### Discrete

Discrete sliders snap to specific values along the rail. They often have defined gaps in the values, like sets of five. 
<img src="https://design.visa.com/assets/components/slider/slider-bp-discrete.svg" alt="A discrete slider with increments visually marked. The slider is labeled Filter by cost with the number 50 next to it and the rail filled half way."/>
- Use discrete sliders when users need to select a distinct number from a range of predefined choices or steps.

#### Continuous

Continuous sliders don’t snap to specific values and can be set anywhere along the range.
<img src="https://design.visa.com/assets/components/slider/slider-bp-continuous-1.svg" alt="A slider labeled Volume with the rail filled half way."/>
- Use continuous sliders when users can select any value from a range, or the specific value is vague or not critical.

## Min-max range
Minimum and maximum values can be added to clarify the slider’s range. Min-max values can be implemented with text or icons. 

### Min-max values in text 
Textual values give exact numbers representing the minimum and maximum. This is helpful when the values are known and relevant to the user. 

<img src="https://design.visa.com/assets/components/slider/slider-min-max-text.svg" alt="A slider with text labels."/>

### Min-max values using icons 
Icon min-max values visualize the range of values without specifying exact numbers. This is helpful when the values are unknown or not relevant to the user. 

<img src="https://design.visa.com/assets/components/slider/slider-min-max-icons.svg" alt="A slider with icon labels."/>

## Behaviors

### Dual-point sliders
A dual-point or double slider indicates an upper and lower boundary. Values can be adjusted from both ends, indicating a starting and ending value. This type of slider can be used instead two sliders and is common for filtering search results. 

<img src="https://design.visa.com/assets/components/slider/slider-behaviors-dual.svg" alt="Slider labeled departure times and the left end labeled 1:30 AM and the right end labeled 9:00 PM. The slider has two end points to drag. Each has a tooltip showning earliest time and latest time."/>

## Content

- Use sentence case without punctuation for all labels.
- Keep labels short to avoid unnecessary truncation. 
- Avoid acronyms or jargon.


---

# accessibility

---
title: Switch
description: Binary control that allows users to toggle between two states like on/off.
meta_description: Find accessibility guidelines for binary controls that allow users to toggle between two states like on/off.
thumbnail: assets/components/switch-graphic.svg
tab_order: 2
---

## Best practices

<br/>
**Note:** The switch component is implemented using a checkbox with `role=&quot;switch&quot;`. Screen readers announce it as “on” and “off” instead of “checked” and “unchecked”. The keyboard behavior and best practices are the same as for the [Checkbox](https://design.visa.com/components/checkbox/accessibility) component.



---

# index

---
title: Switch
tab_title: Code
description: Binary control that allows users to toggle between two states like on/off.
meta_description: Get code for binary controls that allow users to toggle between two states like on/off.
thumbnail: assets/components/switch-graphic.svg
categories:
  - actions
---

## Component Code Examples: switch

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the switch component
const component = parsed.components.find(c => c.name === 'switch');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `switch`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Switch
description: Binary control that allows users to toggle between two states like on/off.
meta_description: Learn how to use binary controls that allow users to toggle between two states like on/off.
keywords: ["Toggle switch", "flip switch", "light switch", "binary switch", "UISwitch (iOS)", "Switch (Android)"]
related:
  components:
    - checkbox
    - radio
    - toggle-button
tab_order: 1
---

Switches are interactive controls used to turn a setting or choice on or off. They’re commonly seen in settings or account configurations.<br/><br/>
Also known as: Toggle switch, flip switch, light switch, binary switch, UISwitch (iOS), Switch (Android).

## Anatomy

<img src="https://design.visa.com/assets/components/switch/switch-anatomy.svg" alt="A switch with a label featured with callout A, a description featured with callout B, and a switch control featured with callout C."/>

**A. Label (required):** Text indicating the purpose of the switch.<br/>
**B. Description (optional):** Optional text that can be used to describe the label in more detail.<br/>
**C. Switch control (required):** Interactive element used to toggle the switch on or off.

## Usage

When to use and when not to use switch

- When to use: For settings that have an on/off or true/false state.
- When not to use: To switch between content views. Use a [toggle button](https://design.visa.com/components/toggle-button) instead.<br/><br/>In place of a [checkbox](https://design.visa.com/components/checkbox) or [radio button](https://design.visa.com/components/radio).

## Best practices

- Don’t use switches in place of radio buttons or checkboxes, except when two radio buttons are being used for a yes/no, on/off, or true/false choice. 
- Ensure labels are placed closed to the switch control so it's clear they're related.
- Ensure the filled state indicates the switch is in the “on” position. 

## Content

- Use sentence case without punctuation for all labels.
- Avoid acronyms or jargon. 
- Keep labels short to avoid unnecessary truncation. 
- Phrase labels to describe what the switch will do in the "on" position. For example, toggling to the "on" position should make the statement true.
- Use full sentences with proper punctuation for descriptions. 
- Limit descriptions to one to two brief sentences.


---

# index

---
title: Tab bar
tab_title: Code
description: Mobile navigation bar that uses icons to navigate between main pages.
meta_description: Get code for mobile navigation bars that use icons to navigate between main pages.
thumbnail: assets/components/tab-bar-graphic.svg
categories:
  - navigation
  - structure-and-layout
---

## Component Code Examples: tab-bar

This component is available in the following libraries:
- **Flutter** (@visa/nova-flutter)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- Flutter → `@visa/nova-flutter`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- Flutter → `flutter`

**Example (Flutter 8.3.1)**:
```javascript
const libraryName = "flutter"; // Determined from Step 1
const version = "8.3.1";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-flutter-8.3.1.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the tab-bar component
const component = parsed.components.find(c => c.name === 'tab-bar');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `tab-bar`

**Available in**:
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples


---

# usage

---
title: Tab bar
description: Mobile navigation bar that uses icons to navigate between main pages.
meta_description: Learn how to use mobile navigation bars that use icons to navigate between main pages.
keywords: ["Bottom navigation", "tab strip", "tab navigation", "tab menu", "UITabBar (iOS)", "TabLayout (Android)"]
related:
  components: 
    - top-app-bar
    - navigation-drawer
    - tabs
    - badge
---

Tab bars enable users to navigate between the main pages of a mobile application. They’re typically anchored to the bottom of the screen on mobile applications. They organize content into labeled tabs and switching tabs takes users to a new page.<br/><br/>
Also known as: Bottom navigation, tab strip, tab navigation, tab menu, UITabBar (iOS), TabLayout (Android).

## Anatomy

<img src="https://design.visa.com/assets/components/tab-bar/tabbar-anatomy.svg" alt="A tab bar with four tabs. The first tab is featured with callout A indicating the icon and callout B indicating the label."/>

**A. Label (required):** Brief text describing the tab content.<br/>
**B. Active tab visual indicator (required):** Visual indicator showing the tab currently in view.<br/> 
**C. Icon (required):** Icon used to represent the tab.

## Usage

When to use and when not to use a tab bar

- When to use: For mobile and tablet platforms.
- When not to use: For web platforms.

- When to use: For main destinations that users need to access from anywhere in the app.
- When not to use: For sub-destinations such as user preferences.

- When to use: When there are three to five linked destinations.
- When not to use: If there are less than three destinations.

## Best practices

  - Reference [Application layouts](https://design.visa.com/patterns/application-layouts) for help deciding which navigation component is best for your use case.
  - Avoid using more than five tabs in the tab bar. 
  - Clearly indicate the active tab to help users understand which tab is related to the information presented.
  - Organize tabs in a logical order, such as placing the most frequently accessed tabs at the beginning.
  - Ensure there’s sufficient touch area for each individual tab to allow for easy and accurate selection.
  - Follow all guidance for implementing [Badges](https://design.visa.com/components/badge) on tab labels.

## Behaviors

### Badges

Tab bar navigation can be paired with number badges in the top right corner of the tab icon to display dynamic information, such as the number of messages. To learn more, reference [Badge](https://design.visa.com/components/badge).

<img src="https://design.visa.com/assets/components/tab-bar/nav-tab-bar-behaviors-badges.svg" alt="A tab bar with a number badge placed to the top right of the inbox tab"/>

## Content

- Write all content in sentence case, except for acronyms or proper nouns, like the application name.
- Don’t use punctuation for navigation items.
- Ensure labels match page titles to enhance the user’s understanding of the site’s information hierarchy. 
- Follow all best practices and guidelines implementing links. Reference [Link](https://design.visa.com/components/link) for more information.  
- Limit labels to a few brief words to prevent unnecessary reflow. 
- Reference [Grammar and punctuation](https://design.visa.com/content/grammar) to learn how to use parallel structure for consistent phrasing.


---

# accessibility

---
title: Table
tab_order: 2
description: Fixed grid that organizes information or data using columns and rows.
meta_description: Find accessibility guidelines for fixed grids that organize information or data using columns and rows.
thumbnail: assets/components/table-graphic.svg
---

## Best practices

- If headers don't provide any functionality, they will not be focusable. Screen readers will be aware of headers by announcing them during navigation. They are also navigable during screen reader's reading or browsing mode.

### Table structure
- Ensure every table has a `&lt;caption&gt;`, which is visually hidden in this library using our screen reader class.
- Ensure the `&lt;caption&gt;` adds meaning to the table heading by giving additional information about the columns or contents.
- Ensure tables have both  `&lt;thead&gt;` and `&lt;tbody&gt;` elements.
- Add `scope=&quot;col&quot;` to the `&lt;th&gt;` elements inside the `&lt;thead&gt;`. Add one row header `&lt;th scope=&quot;row&quot;&gt;` to each row in the table body. The row header is usually the first or second cell. Using scopes greatly improves the experience for people using screen readers. Screen readers will announce a heading label along with the cell content.
- Use `scope`, `id`, and `headers` attributes if there are multiple rows of headers to associate them with the table cells. 

### Table content
- Ensure that each form element ID is unique, which can be easy to forget when generating rows in a loop. 
- Ensure links or buttons use aria-labels to clarify where they lead if the visible text is repeated. For example, if every row has a “Details” link, use “Details of &lt;unique row item&gt;”.

### Dynamic features
- Sortable columns’ `th` elements should have an `aria-sort` attribute with the dynamic value of the state. The header should have a focusable control to trigger the sort.
- Ensure checkboxes used to select a row are programmatically labeled with unique and meaningful text. They can use `aria-label` or `aria-labelledby` to connect them to the id of content in another column.
- Inform users in the table’s `caption` if there’s a control to hide columns.
- Use visible or hidden labels to clarify when external controls (such as search) interact with the table.



---

# index

---
title: Table
tab_title: Code
description: Fixed grid that organizes information or data using columns and rows.
meta_description: Get code for fixed grids that organize information or data using columns and rows.
thumbnail: assets/components/table-graphic.svg
categories:
  - tables
---

## Component Code Examples: table

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the table component
const component = parsed.components.find(c => c.name === 'table');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `table`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples


---

# usage

---
title: Table
tab_order: 1
description: Fixed grid that organizes information or data using columns and rows.
meta_description: Learn how to use fixed grids that organize information or data using columns and rows.
keywords: ["Fixed table", "non-dynamic table", "read-only table", "non-editable table", "constant table", "static table"]
related:
  components:
    - pagination
  patterns:
    - dynamic-table
---

Tables organize and display information using rows and columns, enabling users to access and analyze data. They’re commonly used to sort large amounts of information or present key-value pairs.<br/><br/>
Also known as: Fixed table, non-dynamic table, read-only table, non-editable table, constant table, static table.

## Anatomy

<img src="https://design.visa.com/assets/components/static-table/component-anatomy.svg" alt="A static table with the header section featured by callout A, data rows featured by callout B, data columns featured by callout C, data cells featured by callout D, and pagination controls placed at the bottom of the table featured by callout E."/>

**A. Header row (required):** Row listing the category label for each column.<br/>
**B. Data row (required):** Horizontal grouping of data cells.<br/>
**C. Data column (required):** Vertical grouping of data cells under a category label.<br/>
**D. Data cell (required):** Individual value corresponding to a specific category label.<br/>
**E. Pagination (optional):** A set of links enabling users to navigate a large table split onto multiple pages.

## Usage

When to use and when not to use a table

- When to use: To organize and display data that can be grouped in rows and columns.<br/><br/>For read-only data that would benefit from being structured in a fixed format.
- When not to use: For more complex data that requires user interaction like filtering or exporting. Use a [Dynamic table](https://design.visa.com/patterns/dynamic-table) instead.

## Best practices 

- Limit the data included to ensure all values support the table’s purpose without overwhelming users. 
- Avoid truncating data within cells. If necessary, wrap content to ensure it remains visible. 
- Consider using pagination if the user needs to scroll to see the entire table. 
- Include clear error messaging if data can’t be loaded or if it’s taking longer than expected. 

### Text alignment
Text alignment refers to how data is positioned within a cell, either to the right or left edge. Numeric data is typically right-aligned, while textual data is left-aligned to ensure readability and facilitate comparison of similar data types. Although different alignments can exist within a table, alignment should remain consistent within each column.

<img src="https://design.visa.com/assets/components/static-table/text-indicator.svg" alt="A static table with callouts for a left aligned header and a right aligned header"/>
- Right-align all numeric data such as number count, currency, and dates.
- Left-align textual data such as names, emails, and locations. 
- Ensure row headers match the alignment of the associated cell. 

### Table style
Tables have two styling options to ensure rows and columns are easy to identify: Bands and dividers. Either method can be used to visually group information. Select the one that best fits your users’ data analysis needs.

### Banding
Banding refers to rows that use alternating background colors to help visually group information. 
<img src="https://design.visa.com/assets/components/static-table/static-table-bp-banding.svg" alt="A static table showing three rows in alternating colors"/>

### Dividers
Dividers refer to thin lines used to show separations between rows, columns, or both. 
<img src="https://design.visa.com/assets/components/static-table/static-table-bp-dividers.svg" alt="A static table showing three rows separated by dividers"/>

### Key-value pairs
Tables can be used to present key-value pairs. Key-value pairs refer to datasets with two related pieces of information: A unique identifier or key, and its associated value. This format is useful for displaying structured data where each key is paired with a specific value, making it easy to read and understand.
<img src="https://design.visa.com/assets/components/static-table/static-table-bp-key-value.svg" alt="A static table showing four rows of key value pairs"/>
- Use typography, like bold text, to differentiate the keys from the values. 
- Omit the header row from the table unless it adds important context.

### Group headers
Group headers span across multiple columns to create categories within a table. They’re helpful for data that can be easily grouped or categorized.
<img src="https://design.visa.com/assets/components/static-table/static-table-bp-group-header.svg" alt="A static table using a group header above the column headers"/>
- Consider using group headers if categorizing the table columns would help users analyze or identify the data. 
- Ensure the group headers appear visually different from the header row and general data.

### Pagination
The pagination component is a set of links enabling users to navigate tables divided across multiple pages. This helps reduce cognitive load by reducing the amount of data shown at once. For general information on the pagination component, reference [Pagination](https://design.visa.com/components/pagination/usage).
<img src="https://design.visa.com/assets/components/static-table/dynamic-table-pagination.svg" alt="Pagination for a static table"/>
- Use pagination when the data can’t be easily viewed on one page or requires significant scrolling. 
- Place the pagination component below the last row of the table. 
- Use the default pagination component for complex tables when space permits.
- Use the slim pagination component for less complex tables with fewer pages, or when space is limited. 
- For very complex tables, consider using a [Dynamic table](https://design.visa.com/patterns/dynamic-table) instead to enable users to sort or filter the data. 

## Behaviors

Tables have various behaviors designed to make data easy to understand and interact with. Reference the section below to learn about optional features that can be implemented based on the use case.

### Progress indicators
Progress indicators help users identify when data hasn’t finished loading. This is especially helpful for complex data tables, which can have lengthy load times. For general guidelines on progress indicators, reference [Progress](https://design.visa.com/components/progress/usage).
<img src="https://design.visa.com/assets/components/static-table/dynamic-table-indeterminate-progress-1.svg" alt="Indeterminate progress indicator for a static table"/>
- Use a linear progress indicator in most cases to save space and align with the table layout. 
- Place the indicator at the top of the table, stretching the entire width.
- Consider using skeleton loading as an additional visual indication that the data in the table is loading.
- Ensure the progress indicator uses different visual styling from the table header. 

### Scroll
Scrolling can help users access data when there’s limited vertical space and all rows aren’t visible at once. This helps when there are few columns but many rows, when tables are likely to be viewed on mobile devices, or when you want to maintain the visibility of all columns.<br/><br/>
When implementing vertical scroll, it’s recommended to use a sticky header. Learn more in the section below.
<img src="https://design.visa.com/assets/components/static-table/dynamic-table-indeterminate-progress-2.svg" alt="Scrollbar for a static table"/>
- Ensure the scroll bar is displayed by default so users are aware there's more data available.
- Avoid using a horizontal scroll bar. If there’s enough data that it’s necessary, use a [Dynamic table](https://design.visa.com/patterns/dynamic-table) instead. 

### Sticky header
Sticky headers refer to header rows that remain visible when the user scrolls, ensuring it’s clear what column each cell pertains to. Upon scroll, data rows tuck under the header divider while the sticky header stays fixed at the top. This allows users to view the context of the data they are looking at as they scroll to see more.
<img src="https://design.visa.com/assets/components/static-table/dynamic-table-indeterminate-progress-3.svg" alt="A static table shown with a sticky header as the table rows scroll behind it"/>
- Consider implementing a sticky header when users can’t view all data rows in a single view. 
- Use a [Divider](https://design.visa.com/components/divider/usage) or other visual indicator to ensure the sticky header appears visually different from other rows.
- Use [Elevation](https://design.visa.com/base-elements/elevation/usage) to visually indicate that the sticky header is floating “above” the rest of the table’s data.

## Platform considerations

### Recommended for responsive web only
The table component is designed and built for responsive web applications. When implemented on mobile devices, tables scroll where the screen cuts off, which may limit their accessibility and usability. Use caution implementing tables on screen sizes smaller than 768px.

## Content
- Use simple language—avoid abbreviations or jargon. 
- Use sentence case, except for proper nouns or acronyms.
- Limit use of abbreviations unless the abbreviation is commonly understood and improves readability due to space constraints or line length. 
- Ensure column and row headers have distinct labels. If duplicates are required, add additional context to ensure screen readers can differentiate them. 

### Table titles and subtitles
- Use informative titles that describe the table as a whole.
- Use subtitles to describe complex tables. 
- Don’t include punctuation for table titles.
- Limit titles to three to five descriptive words. If your title can’t be condensed, consider using a subtitle with your title. 
- Limit subtitles to one to two short sentences with punctuation. 

### Column headers
- Clearly label columns using short, concise, and scannable column headers. 
- Ensure column headers accurately describe the contents so users can interpret the data without additional context. 
- Include symbols for units or measurement along with its name. For example “Temperature (°F).”

### Table content
- Use short, scannable content within table rows. 
- Don’t include symbols, such as “$”. Only include those within the header to avoid issues with filtering information.
- Only use punctuation when using decimals. Ensure all decimal places are consistent for filtering information.


---

# accessibility

---
title: Tabs
description: Organizational element that separates content and allows users to switch views.
meta_description: Find accessibility guidelines for organizational elements that separate content and allow users to switch views.
thumbnail: assets/components/tabs-graphic.svg
tab_order: 2
---

## Best practices

<br/>
**Note:** Many of the tab components attributes and behaviors use are handled by our library. As with other form components, use IDs to associate  additional instructions or error messaging so screen readers will read them. Reference [Angular](https://design.visa.com/components/tabs) or [React](https://design.visa.com/components/tabs) for examples.
- Add the `aria-controls=&quot;IDREF&quot;` attribute, which refers to the `tabpanel`, so that it appropriately refers to the tabpanel element associated with the tab.
- Add `aria-selected=&quot;true&quot;` when a user activates a tab, the one associated with the currently displayed panel.
- Add `aria-selected=&quot;false&quot;` for all tab elements in the tab set except the active tab.
- Add `tabindex=&quot;-1&quot;` when a tab is unselected so only the selected tab is in the page Tab sequence.
- Don't set `tabindex=&quot;0&quot;` on the selected (active) tab element.
- Add the attribute `role=&quot;tabpanel&quot;` to the panel containers, as we don’t export a tab panel in our components.
- Consider using `tabindex=&quot;0&quot;` for panels that don’t contain a focusable element to make navigation easier for assistive technology users.

## Keyboard controls
  Keyboard actions and their corresponding behaviors for tabs

- Key: Use the Tab key once to enter the tablist. Hit tab again to exit the group of tabs.

- Key: Moves between the tabs when the component group is in focus in a vertical tablist. <br/> <br/> Focus loops within the tab set. When focus is on the last tab within the set, the down arrow key will move focus to the first tab. When focus is on the first tab within the set, the up arrow key will move focus to the last tab. <br/> <br/> In the automatic update approach, content below the tab should update immediately to match the focused tab.

- Key: Moves between the tabs when the component group is in focus in horizontal tablist. <br/> <br/> Focus loops within the tab set. When focus is on the last tab within the set, the right arrow key will move focus to the first tab. When focus is on the first tab within the set, the left arrow key will move focus to the last tab. <br/> <br/> In the automatic update approach, content below the tab should update immediately to match the focused tab.

- Key: When the interaction requires a manual update, the user must initiate content load with the Enter key after arrow navigation.



---

# index

---
title: Tabs
tab_title: Code
description: Organizational element that separates content and allows users to switch views.
meta_description: Get code for organizational elements that separate content and allow users to switch views.
thumbnail: assets/components/tabs-graphic.svg
categories:
  - selection-controls
  - structure-and-layout
---

## Component Code Examples: tabs

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the tabs component
const component = parsed.components.find(c => c.name === 'tabs');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `tabs`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Tabs
description: Organizational element that separates content and allows users to switch views.
meta_description: Learn how to use organizational elements that separate content and allow users to switch views.
keywords: ["Tabbed interface", "tab group", "TabLayout (Android)", "TabItem (Android)"]
related:
  components:
    - accordion
    - anchor-link-menu
tab_order: 1
---

Tabs are organizational elements that group related content. They help users navigate between sections of content by switching views within the same page or container.<br/><br/>
Also known as: Tabbed interface, tab group, TabLayout (Android), TabItem (Android).

## Anatomy

<img src="https://design.visa.com/assets/components/tabs/tabs-anatomy.svg" alt="A group of four tabs where the first tab is selected. All tabs have a label featured with callout A and an icon featured with callout B. The selected tab is identified by a bottom border visual indicator featured with callout C."/>

**A. Label (required):** Brief text describing the tab content.<br/>
**B. Icon (optional):** Icon used to represent the tab.<br/>
**C. Active tab visual indicator (required):** Visual indicator showing the tab currently in view.

## Usage

When to use and when not to use different types of tabs

- Component: When there are more categories of content and longer tab labels.
- When to use: If your interface has limited vertical space.

- Component: When there are fewer categories of content and shorter tab labels.
- When to use: When the tab labels are long and can lead to truncation of text.

- Component: When tab labels are short and concise and using icons helps call attention to the content.
- When to use: When tab labels are longer and icons don’t add additional context.

## Best practices
- Reference [Application layouts](https://design.visa.com/patterns/application-layouts) for help deciding which navigation component is best for your use case.
- Organize tabs in a logical order, such as placing the most frequently accessed tabs at the beginning.
- Clearly indicate the active tab to help users understand which tab is related to the information presented.
- Limit the number of tabs to avoid overwhelming users. If you have more than five tabs, consider using a different navigation pattern.
- Avoid displaying disabled tabs without providing an explanation for why the tab is disabled.

### Vertical tabs
Vertical tabs are arranged in a single column on the left side of the content area for left-to-right languages. They’re ideal for interfaces with long tab labels or when there are many categories of content.

<img src="https://design.visa.com/assets/components/tabs/tabs-bp-vertical-tabs.svg" alt="A set of four vertical tabs stacked on top of each other with the first one being active"/>
- Place the vertical tabs on the left side of the content area to align with common left-to-right reading patterns.
- Ensure the tab list is scrollable if necessary to prevent overwhelming users with too many choices at once.
- Consider using a nav menu to group related tabs and reduce clutter.
<br/>
**Note:** Nav menus are built using a modified [dropdown menu](https://design.visa.com/components/dropdown-menu) component. For accessibility reasons, don’t use the default dropdown menu or replace it with a select component. Always consult with accessibility partners before modifying the behavior of any component.

### Horizontal tabs
Horizontal tabs are arranged in a single row at the top of the content area. They’re best used when there are fewer categories of content and shorter tab labels to avoid truncation.

<img src="https://design.visa.com/assets/components/tabs/tabs-bp-horizontal-tabs.svg" alt="A set of four horizontal tabs arranged next to each other with the first one being active"/>
- Limit the length of tab labels to avoid wrapping or truncation. 
- Avoid using more than five to seven tabs.
- Ensure horizontal tabs adapt to different screen sizes. Consider using a nav menu for additional tabs on smaller screens.

### Stacked tabs
Stacked tabs are similar to horizontal tabs except they include an icon above the tab label. These are best used when more context could be added to tabs using by icons to represent the label in more detail.

<img src="https://design.visa.com/assets/components/tabs/tabs-bp-stacked.svg" alt="A set of three stacked tabs arranged next to each other with the first one being active"/>

## Behaviors
Tabs have various behaviors designed to make content easy to understand and interact with.

### Tabs for in-page content
The expected behavior of tabs is to enable users to access different information within a single page area. They should be positioned below the page title to prevent confusion with site navigation. Place related tabs next to the corresponding content and apply visual styling to emphasize their relationship.

<img src="https://design.visa.com/assets/components/tabs/tab-bp-usage-content.svg" alt="A set of three stacked tabs arranged next to each other with the first one being active"/>
- Place tabs near their related content.
- Use visual styling to clearly indicate the active tab.

### Scaling and reflow
Scaling and reflow refer to how tabs behave as the container size changes, especially when the container is too small to display all content at once. Tabs should adjust responsively to maintain usability and clarity, wrapping or reflowing as needed to fit within the available space.

<img src="https://design.visa.com/assets/components/tabs/tabs-bp-scaling.svg" alt="Horizontal and vertial tab groups with 6px spacing between each tab"/>
- Ensure consistent margins and 6 px padding between tab elements to maintain a clean and organized layout. 
- Ensure tabs are responsive and adapt to different screen sizes without causing truncation or hiding content.

## Platform considerations

### Mobile

#### Tabs as navigation

While the typical expected behaviors for tabs is to switch between views within the same page, they can also be used as the basis for navigation components, like [tab bar](https://design.visa.com/components/tab-bar). When implemented as a tab bar, switching tabs takes users to a new page.
<img src="https://design.visa.com/assets/components/tabs/tab-bp-usage-nav.svg" alt="A simplified layout with a tab bar at the bottom of the page"/>

#### Fixed width

When space and content allows, tab groups on small screens can extend to the width of the screen. Both native mobile and responsive web applications can use this layout.
<img src="https://design.visa.com/assets/components/tabs/tabs-platform-fixed.svg" alt="A simplified mobile screen layout with two tabs filling the width of the screen"/>

#### Scrollable tabs (touch devices)

Tabs may overflow horizontally on touch devices, allowing users to scroll through them. This layout isn’t for use on desktop devices.
<img src="https://design.visa.com/assets/components/tabs/tabs-platform-scroll.svg" alt="A simplified mobile screen layout with one row of tabs. The third tab's label is cropped, to show that more can be seen on scroll."/>

#### Stacked tabs (non-touch devices)

In the rare instance of a small screen without touch capabilities, tabs may be stacked on top themselves. Consider using an [accordion](https://design.visa.com/components/accordion) instead of tabs to save space.
<img src="https://design.visa.com/assets/components/tabs/tabs-platform-stacked.svg" alt="A simplified mobile screen layout with two rows of tabs"/>

## Content
- Write all content in sentence case, except for acronyms or proper nouns, like the application name.
- Don’t use punctuation for tab labels.
- Ensure labels match page titles to enhance the user’s understanding of the site’s information hierarchy. 
- Follow all best practices and guidelines implementing links. Reference [Link](https://design.visa.com/components/link) for more information.  
- Limit labels to a few brief words to prevent unnecessary reflow. 
- Reference [Grammar and punctuation](https://design.visa.com/content/grammar) to learn how to use parallel structure for consistent phrasing.


---

# accessibility

---
title: Toggle button
description: Selection element that allows users to switch between states or views.
meta_description: Find accessibility guidelines for selection elements that allow users to switch between states or views.
thumbnail: assets/components/toggle-graphic.svg
tab_order: 2
---

## Best practices

<br/>
Toggle buttons are implemented in several ways in our library. Single-select toggles are implemented as radios or buttons while multi-select toggles are implemented as checkboxes or buttons. Best practices and keyboard behavior follow the type of control being used. 
- Ensure toggle containers wrap for narrow screens and high zoom levels.
- Use the `aria-pressed` attribute if you are using button components.

## Keyboard controls

### Single-select toggle buttons

Keyboard actions and their corresponding behaviors for single-select toggle buttons

- Key: Moves the focus and selection to the next option in the group and unselects the previously focused one. <br/><br/>
Focus moves in a circular rotation within the group, so progressing past the last option returns focus to the first in the group.

- Key: Moves to the next focusable element outside the toggle button group.

### Multi-select toggle buttons

Keyboard actions and their corresponding behaviors for multi-select toggle buttons

- Key: Selects/unselects the toggle button when the component is in focus.

- Key: Moves keyboard focus to the next checkbox in a group or next interactive element.



---

# index

---
title: Toggle button
tab_title: Code
description: Selection element that allows users to switch between states or views.
meta_description: Get code for selection elements that allow users to switch between states or views.
thumbnail: assets/components/toggle-graphic.svg
categories:
  - actions
  - selection-controls
---

## Component Code Examples: toggle

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the toggle component
const component = parsed.components.find(c => c.name === 'toggle');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `toggle`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Toggle button
description: Selection element that allows users to switch between states or views.
meta_description: Learn how to use selection elements that allow users to switch between states or views.
keywords: ["Flip button", "state button", "selector", "UISegmentedControl (iOS)", "toggle button (Android)"]
related:
  components:
   - tabs
   - switch
   - checkbox
   - radio
tab_order: 1
---

Toggles are selection tools, typically used to change the view of page information or apply a setting. They’re typically used in data visualization contexts like tables or graphs, forms, search results, and settings pages.<br/><br/>
Also known as: Flip button, state button, selector, UISegmentedControl (iOS), toggle button (Android).

## Anatomy

<img src="https://design.visa.com/assets/components/toggle/toggle-anatomy.jpg" alt="A group of three toggle buttons labeled 'Label 1', 'Label 2', and 'Label 3'. The first toggle button is pressed, with a label featured by callout A and a leading icon featured by callout B."/>

**A. Label (optional):** Text describing the toggle button.<br/>
**B. Icon (optional):** Leading or trailing icon used instead of a label or to enhance its meaning.

## Usage

When to use and when not to use different types of toggle buttons

- Component: To change the view of a dataset.<br/><br/>When only one button can be active at a time.
- When to use: To change between pages or content sections. Use [tabs](https://design.visa.com/components/tabs/usage) instead.

- Component: To apply settings.<br/><br/>When any number of buttons may be active, including none.
- When to use: To perform actions or to group unrelated concepts.

## Best practices
- Don’t use toggles in place of [radio buttons](https://design.visa.com/components/radio/usage) or [checkboxes](https://design.visa.com/components/checkbox/usage). 
- Ensure toggles within the same group are related and apply to the same element within the interface. 
- Place toggles near the element they control to ensure their purpose and function is clear. 
- Limit toggle groups to four or five buttons to avoid overwhelming users. 

## Behaviors

Toggle buttons have two functionalities:

### Single-select

Single-select toggle buttons can only be selected one at a time. They represent options that can’t be applied at the same time, like separate views of a dataset. One button is always active, and selecting an inactive button deactivates the active button.
<img src="https://design.visa.com/assets/components/toggle/toggle-bp-mutually-exclusive.jpg" alt="A group of three toggle buttons that have leading icons, where 'Map view' is selected and 'List view' and 'Grid view' are unselected."/>

### Multi-select

Multi-select toggle buttons can have any number of buttons selected, including none. They’re commonly used to apply settings. Selecting an inactive button does not affect any active buttons. This is the only type of toggle that can be used alone to represent a single option.
<img src="https://design.visa.com/assets/components/toggle/toggle-bp-independent.jpg" alt="An icon toggle button with a pin icon followed by an icon button layout with a plane icon, train icon, and car icon"/>

## Content

- Use sentence case without punctuation for all labels.
- Avoid acronyms or jargon. 
- Keep labels short to avoid unnecessary truncation. 
- Phrase labels so selecting the toggle makes the statement true.



---

# accessibility

---
title: Tooltip
description: Short message communicating the function or context of a control or object.
meta_description: Find accessibility guidelines for short messages communicating the function or context of a control or object.
thumbnail: assets/components/tooltip-graphic.svg
tab_order: 2
---

## Best practices

- Ensure all tooltips are accessible using the keyboard as well as a mouse.
- Ensure the tooltip is attached to a focusable trigger object. 
- Ensure the tooltip’s triggering object has `aria-describedby` with a value of the tooltip span’s `id`.

## Keyboard controls

  Keyboard actions and their corresponding behaviors for tooltips

- Key: Moves focus to the tooltip’s trigger object. When that object is receives focus, the tooltip appears. When it loses focus, the tooltip disappears.

- Key: Dismisses tooltip.



---

# index

---
title: Tooltip
tab_title: Code
description: Short message communicating the function or context of a control or object.
meta_description: Get code for short messages communicating the function or context of a control or object.
thumbnail: assets/components/tooltip-graphic.svg
categories:
  - feedback-and-status
---

## Component Code Examples: tooltip

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the tooltip component
const component = parsed.components.find(c => c.name === 'tooltip');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `tooltip`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Tooltip
description: Short message communicating the function or context of a control or object.
meta_description: Learn how to use short messages communicating the function or context of a control or object.
keywords: ["Help text", "hint", "info tip", "screen tip", "TooltipCompat (Android)"]
related:
  components:
    - dialog
  content:
    - accessible-text
tab_order: 1
---

Tooltips provide brief, contextual information about a control or element. They appear when users hover over the element with their cursor, or when it receives keyboard focus.<br/><br/>
Also known as: Help text, hint, info tip, screen tip, TooltipCompat (Android).

## Anatomy

<img src="https://design.visa.com/assets/components/tooltip/tooltip-anatomy.svg" alt="A tooltip featured by callout A indicating the required label."/>

**A. Label (required):** Brief text providing information about a selected control or element.

## Usage

When to use and when not to use tooltip

- When to use: To give users supplementary details or context about a control or element.
- When not to use: For important information that needs to always be visible to users.

## Best practices

  - Ensure tooltips provide relevant and helpful information that’s directly related to the element they’re associated with.
  - Ensure tooltips are easily noticeable but don’t obscure their associated element or other important information.
  - Ensure users can easily dismiss tooltips, especially if they hover over them accidentally. Tooltips should disappear when the user moves the cursor away or removes focus.

## Behaviors

### Paired component examples

#### Icon button

Include tooltips in icon buttons that aren’t labeled on screen, or when they may be hard to identify.<br/><br/>
**Note:** Tooltips aren’t equivalent to image alt text. Reference [Acessible text](https://design.visa.com/content/accessible-text) to learn more. 
<img src="https://design.visa.com/assets/components/tooltip/tooltip-behaviors-icon.svg" alt="Example of a tooltip used with an icon button"/>

#### Sliders

Show tooltips with the value when the user interacts with a [slider](https://design.visa.com/components/slider).
<img src="https://design.visa.com/assets/components/tooltip/tooltip-behaviors-sliders.svg" alt="Example of a tooltip used with a slider"/>

#### Table header tooltips

Provide tooltips for category headers if needed to add additional context for the user.
<img src="https://design.visa.com/assets/components/tooltip/tooltip-behaviors-table-header.svg" alt="Example of a tooltip used with a table header"/>

### Displaying content animation
When the mouse hovers over an element, the tooltip may appear with a delay of up to 500 milliseconds (0.5 seconds). Once the mouse moves away, the tooltip will disappear. When an element receives keyboard focus, the tooltip will immediately be displayed with the associated element, and it will disappear once the keyboard focus moves away.

Delay timing for hover, keyboard, and disappearing

- Appear delay (hover): Up to 500ms
- Appear delay (keyboard): None
- Disappear delay: None

## Placement
The recommended placement for tooltips is two pixels from the clickable area, center aligned from the top, bottom, left, or right side of the interactive element. Tooltip placement can be programmatically determined based on the position of the element on the screen to ensure it's always visible.
<img src="https://design.visa.com/assets/components/tooltip/placement.svg" alt="Example of a tooltip used with an icon button with the tooltip appearing two pixels above the button"/>

## Content

- Write all content in sentence case, except for acronyms or proper nouns.
- Don’t use punctuation for tooltips.
- Use abbreviations only when commonly understood.
- Limit labels to a few brief words.
- Reference [Grammar and punctuation](https://design.visa.com/content/grammar) to learn how to use parallel structure for consistent phrasing.


---

# index

---
title: Top app bar
tab_title: Code
description: Navigation fixed to the top of mobile apps with logo, links, and global search. 
meta_description: Get code for navigation fixed to the top of mobile apps with logo, links, and global search.
thumbnail: assets/components/top-app-bar-graphic.svg
categories:
  - navigation
  - structure-and-layout
---

## Component Code Examples: top-app-bar

This component is available in the following libraries:
- **Flutter** (@visa/nova-flutter)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- Flutter → `@visa/nova-flutter`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- Flutter → `flutter`

**Example (Flutter 8.3.1)**:
```javascript
const libraryName = "flutter"; // Determined from Step 1
const version = "8.3.1";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-flutter-8.3.1.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the top-app-bar component
const component = parsed.components.find(c => c.name === 'top-app-bar');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `top-app-bar`

**Available in**:
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Top app bar
description: Navigation fixed to the top of mobile apps with logo, links, and global search. 
meta_description: Learn how to use navigation fixed to the top of mobile apps with logo, links, and global search.
keywords: ["App header", "navigation bar", "menu bar", "app bar", "NavigationBar (iOS)", "Toolbar (Android)"]
related:
  components:
    - navigation-drawer
    - horizontal-navigation
  content:
    - information-architecture
tab_order: 1
---

The top app bar is a container enabling users to navigate mobile products or experiences. It's usually placed at the top of an app or website and turns into a [horizontal navigation](https://design.visa.com/components/horizontal-navigation/usage) bar on larger screens.<br/><br/>
Also known as: App header, navigation bar, menu bar, app bar, NavigationBar (iOS), Toolbar (Android).

## Anatomy

<img src="https://design.visa.com/assets/components/top-app-bar/nav-topappbar-anatomy.svg" alt="A top app bar with a hamburger menu featured by callout A indicating the menu icon, a 'VISA' logo featured by callout B indicating the brandmark, a search icon featured by callout C indicating the global search button, and an avatar icon featured by callout D indicating the user profile button."/>

**A. Menu icon (optional):** Menu containing links to navigate through the application.<br/>
**B. Brand mark (optional):** Visual element representing Visa, a partner brand, or a fictitious brand associated with the product.<br/>
**C. Global search (optional):** Icon button prompting a global search bar to find content across the whole site or app.<br/>
**D. User profile (optional):** Avatar component representing the current user’s account.

## Usage

When to use and when not to use top app bar

- Component: As a simple solution for navigating mobile applications.
- When to use: For larger screen sizes. Use [horizontal navigation](https://design.visa.com/components/horizontal-navigation/usage) instead.

- Component: To provide easy access to global search.
- When to use: If the app is designed for a specific task and doesn’t contain a lot of searchable content.

- Component: For the child pages of an application.
- When to use: If your app only has one page, a page title may not be necessary.

## Best practices
- Reference [Application layouts](https://design.visa.com/patterns/application-layouts) for help deciding which navigation component is best for your use case.
- Ensure the order of the navigation items is consistent throughout the application, as changing the order may confuse users.
- Consider making the brand mark and/or application name function as a link to the homepage of the experience.
- Ensure the top app bar is visible at all times, or have a clear way to bring it back into view when hidden.
- Follow all guidance found in [Search](https://design.visa.com/patterns/search), [Navigation drawer](https://design.visa.com/components/navigation-drawer/usage), and [Avatar](https://design.visa.com/components/avatar/usage) when implementing those items in the navigation. 

### Icons
Top app bars use icons to save space and enable quick access to important functions. There are two types of icons, leading and trailing.

#### Leading icons

The leading icon refers to the icon on the left side of the screen for left-to-right languages. This icon is reserved for navigational purposes. In the default view, it’s used to expand a [navigation drawer](https://design.visa.com/components/navigation-drawer/usage). In certain cases, it can be replaced with a upward or backward arrow to move users to their previous screen. To learn more, reference the [Page title](https://design.visa.com/components/top-app-bar/usage#page-title) section below. 

<img src="https://design.visa.com/assets/components/top-app-bar/nav-topappbar-bp-leading.svg" alt="A top app bar with emphasis on leading hamburger menu icon"/>
- Use one leading icon for navigation purposes only.

#### Trailing icons
Trailing icons refer to the icon(s) on the right side of the screen for left-to-right languages. These icons are used to represent common actions, like global search or account settings.

<img src="https://design.visa.com/assets/components/top-app-bar/nav-topappbar-bp-trailing.svg" alt="A top app bar with emphasis on trailing avatar icon."/>
- Place the most-used actions toward the left and least-used actions on the right.
- Limit trailing icons to one or two to avoid overcrowding the menu. 
- Only use commonly understood icons to ensure their purpose is clear.

## Behaviors

### Scrolling
By default, the top app bar is hidden when the user scrolls down on the page to provide full use of the screen. If the top app bar contains important actions, it can be fixed at the top of the screen for easy access.

  
  #### Scrolls with content
    <img src="https://design.visa.com/assets/components/top-app-bar/nav-topappbar-behaviors-scroll.svg" alt="Top app bar titled 'Newsfeed' with a back button on the left and a search button on the right. Top app bar slowly moves out of view window as content is scrolled."/>
  
  
  #### Stays fixed at top
    <img src="https://design.visa.com/assets/components/top-app-bar/nav-topappbar-behaviors-fixed.svg" alt="Top app bar titled 'Newsfeed' with a back button on the left and a search button on the right. Top app bar stays in position as content is scrolled."/>
  

### Page title
The page title variant is a modified top app bar used for child pages in an application. In this use case, the brandmark is replaced by the current page title, and the hamburger menu is a back arrow enabling users to navigate back to the parent page.

<img src="https://design.visa.com/assets/components/top-app-bar/nav-topappbar-behaviors-title.svg" alt="Top app bar titled 'Newsfeed' with a back button on the left and a search button on the right."/>

### Top app bars as chat navigation
Top app bars can be used as navigation components within chat layouts. The icons can be further customized based on the layout or the intended user function. When implemented in panel chats, top app bar buttons may include a hamburger menu or options menu. The modal chat is less complex and may include minimize and close buttons. Reference [Chat](https://design.visa.com/patterns/chat) for more information.

<img src="https://design.visa.com/assets/components/top-app-bar/tab-bp-usage-nav.svg" alt="Top app bar with hamburger menu on the left, brandmark centered, and user profile button on the right"/>

## Platform considerations

### Mobile
Top app bars are used for mobile or very small responsive web screens. As screen size increases, its behavior changes to utilize the additional space.
<img src="https://design.visa.com/assets/components/top-app-bar/nav-horizontal-platform-mobile.svg" alt="Two modal chats with different top app bars. One on the left with 'Chat name' as the title, a hamburger menu, and a three dot button and one on the right with 'Chat' as the title, a minimize button, and a close button"/>

#### 768 px (tablet)

As screen size increases for tablets or smaller web screens, the top app bar turns into the 786px [horizontal navigation](https://design.visa.com/components/horizontal-navigation/usage) component. The lower the resolution, the simpler the navigational bar appears in the viewport. At this size, links are placed in the hamburger menu and the application name and brand mark are centered instead of left-aligned.

<img src="https://design.visa.com/assets/components/top-app-bar/nav-topappbar-platform-med.svg" alt="Top app bar with hamburger menu on the left, brandmark and application name centered, and search button on the right"/>

### Web

When the screen size increases past 768 px, the top app bar turns into a [horizontal navigation](https://design.visa.com/components/horizontal-navigation/usage) component. At this size, links are displayed horizontally.

<img src="https://design.visa.com/assets/components/top-app-bar/nav-horizontal-platform-large.svg" alt="Horizontal navigation with brandmark 'VISA Digitial Currency Hub', links 'L1 Label 1', 'L1 Label 2', 'L1 Label 3' and trailing search and user profile icons."/>

## Content
- Write all content in sentence case, except for acronyms or proper nouns, like the application name.
- Don’t use punctuation for navigation items.
- Ensure labels match page titles to enhance the user’s understanding of the site’s information hierarchy. 
- Follow all best practices and guidelines implementing links. Reference [Link](https://design.visa.com/components/link) for more information.  
- Limit labels to a few brief words to prevent unnecessary reflow. 
- Reference [Grammar and punctuation](https://design.visa.com/content/grammar) to learn how to use parallel structure for consistent phrasing.


---

# accessibility

---
title: Vertical navigation
description: Navigation panel located next to page content on screens with sufficient space.
meta_description: Find accessibility guidelines for navigation panels located next to page content on screens with sufficient space.
thumbnail: assets/components/vertical-graphic.svg
tab_order: 2
---

## Best practices

<br/>
**Note:** Vertical navs are made up of multiple components. Follow guidelines for each of those. 
- Use a native HTML `header` landmark.
- Ensure any `nav` landmark elements have unique and descriptive `aria-labels`. The label text should not include the word “navigation” as the screen reader will already announce that and it will be redundant.
- Only use a `header` element for the primary navigation if your application has both top and side navigation.
- Use `aria-curent=&quot;page&quot;` on the link which leads to the current page. Links in the vertical menu look like tabs and use css classes for tabs, but are not tabs and don’t have tab roles.
- Ensure the content in the nav responds to a small window. 

### Logos

Our library has a classname just for the application name in the horizontal navigation component. There is a component for the Visa logo that adjusts for the user’s high contrast settings.
- Ensure the logo has an accessible name or is inside a link with an accessible name with `aria-hidden=&quot;true&quot;` on the svg.
- Use one of the library’s classes for high contrast for a logo with light or dark foreground if you use a different logo, as setting a contrasting background behind the brand logo ensures it will have maximum contrast in high contrast mode without a visible change in default contrast mode.

### Skip to main content link

The skip to main content link allows keyboard users to go directly to the main content of the page. This link is first in the DOM (unless there is a skip to login link). It appears when users land on the page and activates the tab key and is only visible when it receives keyboard focus. Activating the link moves focus to the `main` component. <br/> <br/> Reference the [examples](https://design.visa.com/components/vertical-navigation) to learn how to implement VPDS’s skip-link styles.
<img src="https://design.visa.com/assets/components/vertnav/vertnav-accessibility-visual.svg" alt="A vertical navigation bar and a skip to main content link"/>

### Skip to log in link

When navigation includes an account log in, the skip to log in link will appear when users press tab after page load and is tacked onto the top of the navigation bar. If user presses tab again, the user will be prompted with the skip to main content link. 
<img src="https://design.visa.com/assets/components/vertnav/vertnav-accessibility-visual-1.svg" alt="A vertical navigation bar and a skip to log in link"/>

## Keyboard controls

Keyboard actions and their corresponding behaviors for vertical navigation

- Key: Moves focus to the next focusable element.

- Key: Prompts the button when focused.

- Key: Moves keyboard focus backwards to the previous interactive element in the navigation.



---

# index

---
title: Vertical navigation
tab_title: Code
description: Navigation panel located next to page content on screens with sufficient space.
meta_description: Get code for navigation panels located next to page content on screens with sufficient space.
thumbnail: assets/components/vertical-graphic.svg
categories:
  - navigation
  - structure-and-layout
---

## Component Code Examples: vertical-navigation

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the vertical-navigation component
const component = parsed.components.find(c => c.name === 'vertical-navigation');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `vertical-navigation`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# usage

---
title: Vertical navigation
tab_order: 1
description: Navigation panel located next to page content on screens with sufficient space.
meta_description: Learn how to use navigation panels located next to page content on screens with sufficient space.
keywords: ["Vertical menu", "sidebar navigation", "vertical navigation bar", "left/right navigation bar", "column navigation", "UINavigationController (iOS)", "Vertical ScrollView (Android)"]
related:
  components: 
    - horizontal-navigation
    - navigation-drawer
  content:
    - information-architecture
---

The vertical navigation component is a container enabling users to navigate a product or experience. It’s common on sites or applications with many links that may not fit horizontally.<br/><br/>
Also known as: Vertical menu, sidebar navigation, vertical navigation bar, left/right navigation bar, column navigation, UINavigationController (iOS), Vertical ScrollView (Android).

## Anatomy

<img src="https://design.visa.com/assets/components/vertnav/nav-vertical-anatomy.svg" alt="A vertical navigation with 'VISA' featured by callout A indicating the brandmark, 'Application name' featured by callout B, 'SECTION TITLE' featured by callout C, navigation links with icons and labels featured by callouts D and E, expand/collapse icons featured by callout F, a scrollbar featured by callout G, a user profile featured by callout H, and a collapse icon button featured by callout I."/>

**A. Brand mark (optional):** Visual element representing Visa, a partner brand, or a fictitious brand associated with the product.<br/>
**B. Application name (optional):** Label indicating the name of the application.<br/>
**C. Section title (optional):** Title used to group navigation elements.<br/>
**D. Icon (optional):** Visual indicator used to enhance the meaning of the navigation link label.<br/>
**E. Navigation link (required):** Label indicating the destination of the link.<br/>
**F. Chevron (optional):** Icon indicating the collapsed or expanded state of a nested navigation item.<br/>
**G. User profile (optional):** Avatar component representing the current user’s account.<br/>
**H. Collapse icon (optional):** UI icon button used to collapse or expand the vertical navigation from the left side of the screen.

## Usage

When to use and when not to use vertical navigation

- When to use: For a large number of navigation items.<br/><br/>When horizontal space is limited.
- When not to use: If vertical space is limited.<br/><br/>If there are only a few navigational items, use [Horizontal navigation](https://design.visa.com/components/horizontal-navigation/usage) instead.

## Best practices
- Reference [Application layouts](https://design.visa.com/patterns/application-layouts) for help deciding which navigation component is best for your use case.
- Ensure the order of the navigation items is consistent throughout the application, as changing it may confuse users.
- Ensure text within the navigation panel wraps to a second line instead of truncating to ensure it’s fully visible to users. 
- Include a vertical scroll bar if all navigation items can’t be viewed at once. 
- Consider making the brand mark and/or application name function as a link to the homepage of the experience.
- Follow all guidance found in [Link](https://design.visa.com/components/link/usage) and [Avatar](https://design.visa.com/components/avatar/usage) for implementing a user profile in the navigation panel. 

### Section titles and nesting
Section titles refer to static text used to group navigation items under a common category. They can be used with or without nested navigation items, which expand or collapse other navigation items. Both methods group related content and help users navigate easily. Decide which to use based on your use case and design preferences.

         
          #### Section titles
          Section titles group navigation items without nesting them. They’re helpful for grouping items that should always be visible within the menu.  
          <img src="https://design.visa.com/assets/components/vertnav/accordion-chevron-collapse-1.svg" alt="A vertical navigation with tabs grouped under two section titles: 'Account managment' and 'Customer service.'"/>
          - Use section titles to group items that should always be visible in the menu.      
      
         
          #### Nesting
          Nesting items group links within collapsible sections. They’re helpful for more complex apps menus may benefit from limiting the number of links visible at once.          
          <img src="https://design.visa.com/assets/components/vertnav/accordion-chevron-expand-1.svg" alt="A vertical navigation with three tabs nested under an 'Account management' tab and one tab nested under a 'Customer service' tab."/>
          - Consider nesting items in longer navigation menus, as this can help save space and declutter the experience.         
      

### Icon usage
Icons can be used in navigation menus to make scanning easier and reinforce familiar ideas.
<img src="https://design.visa.com/assets/components/vertnav/vertnav-bp-icons.svg" alt="A vertical navigation bar with level 1 and level 2 section headers. Level 1 section headers have leading icons while level 2 section headers do not have icons."/>
- Ensure icon usage applies to all navigation items within the same hierarchy level. For example, if you use icons for some L1 labels, they should be used in all L1 items. 
- Omit icons for nested items, but if they’re necessary, ensure all items within the nested level has one.

## Behaviors

### Scrolling
A scroll bar can be used if the navigation is long and doesn’t fit in one view. The navigation items will scroll, while the brand mark, application name, and any items at the bottom remain fixed in position.
<img src="https://design.visa.com/assets/components/vertnav/verticalnav-behaviors-scroll.svg" alt="A vertical navigation bar with a scrollbar"/>

### Collapsed state
Vertical navigation menus can include a collapse button enabing users to expand or collapse the whole menu as needed. 
<img src="https://design.visa.com/assets/components/vertnav/verticalnav-behaviors-collapsed.svg" alt="A vertical navigation bar in its collapsed state."/>
- Consider implementing a collapse button if users would benefit from additional horizontal space in the main content area.

### Chevron direction
Visually differentiate expanded and collapsed sections using the chevron direction.

         
          #### Collapsed
          Collapsed sections should use the downwards-pointing chevron to indicate collapsed content can be expanded.  
          <img src="https://design.visa.com/assets/components/vertnav/accordion-chevron-collapse-2.svg" alt="Two collapsed tabs labeled 'Account management' and 'Customer service'."/>    
      
       
          #### Expanded
          Expanded sections should use the upwards-pointing chevron to indicate expanded content can be collapsed.          
          <img src="https://design.visa.com/assets/components/vertnav/accordion-chevron-expand-2.svg" alt="Two expanded tabs, labeled 'Account management' and 'Customer service,' to show the tabs nested under each one."/>      
      

## Platform considerations

### Mobile
Vertical navigation is recommended for web applications only. For responsive navigation on small screen sizes, or for mobile designs, consider using a [Navigation drawer](https://design.visa.com/components/navigation-drawer/usage) instead, which is prompted from a hamburger menu and overlays the page content.

<img src="https://design.visa.com/assets/components/vertnav/notificationtray-platform.svg" alt="A vertical navigation appearing on a mobile layout, obscuring the page content to show an 'Accounts' tab, an active 'Trading' tab, a 'Services' tab, a 'Notifications' tab, and an account profile tab labeled 'Alex Miller'"/>

## Content
- Write all content in sentence case, except for acronyms or proper nouns, like the application name.
- Don’t use punctuation for navigation items.
- Ensure labels match page titles to enhance the user’s understanding of the site’s information hierarchy. 
- Follow all best practices and guidelines implementing links. Reference [Link](https://design.visa.com/components/link/usage) for more information.  
- Limit labels to a few brief words to prevent unnecessary reflow. 
- Reference [Grammar and punctuation](https://design.visa.com/content/grammar) to learn how to use parallel structure for consistent phrasing.


---

# index

---
title: Accessible text
description: Learn how to effectively apply alternative text and ARIA labels for improved accessibility. 
meta_description: Learn how to effectively apply alternative text and ARIA labels for improved accessibility.
thumbnail: assets/content/accessible-text-graphic.svg
header_image: assets/content/alt-text-overview.svg
---

Accessible text refers to text used to improve the accessibility of web content. It includes all text included in the code to help assistive technology users understand and interact with interface elements. <br/><br/>

This guidance gives an overview of how to effectively apply alternative text and ARIA labels for improved accessibility. For more guidance on creating inclusive digital experiences, visit [Accessibility](https://design.visa.com/global-accessibility-requirements). Internal users can also visit the [Visa Accessibility SharePoint](https://bookmarks.visa.com/vpds-vgar-accessibility).

## Alt attributes
Alternative text (also known as alt text, alt attributes, or alt descriptions) refers to HTML attributes that provide text descriptions for images. It’s an important accessibility consideration, enabling screen readers to announce descriptions to users who may not be able to perceive images otherwise.

### Screen reader optimization
Alt text descriptions should be written carefully to ensure it's clear and understandable to users. Follow the guidance below to ensure the best experience.
- Use proper punctuation and grammar to ensure descriptions are easy to understand. To learn more, reference [Grammar and punctuation](https://design.visa.com/content/grammar).
- Include a space as the first character in a description to ensure the screen reader pauses before announcing it. This helps users distinguish descriptions from other text. 
- Consider hiding decorative images that don’t add meaning by including a null, or empty text alternative. 
- Limit text alternatives to one sentence. If you need more than one short sentence to describe an image, which is often true for graphs or diagrams, use a two-part description method as outlined by the [Web Accessibility Initiative](https://www.w3.org/WAI/tutorials/images/complex/)<!-- aria-label="Web Accessibility Initiative (opens in a new tab)" -->.

## Accessible Rich Internet Applications (ARIA) labels
ARIA (Accessible Rich Internet Applications) labels are attributes used in HTML to improve accessibility. They are particularly useful for content that’s difficult for people using screen readers and other assistive technology to understand. ARIA labels provide critical information to ensure these users can navigate and interact with interface elements.

### Best practices

- Use an ARIA label when an element doesn’t have a descriptive name or the name doesn’t provide enough context to understand what the element does. 
- Don’t use ARIA and alt-text together to avoid redundancy. Use alt text for HTML img elements, and ARIA labels for other elements with the img role. 
- Avoid using ARIA labels if they don’t add meaningful context. For more information, reference [No ARIA is better then Bad ARIA](https://www.w3.org/WAI/ARIA/apg/practices/read-me-first/)<!-- aria-label="No ARIA is better then Bad ARIA (opens in a new tab)" --> from WCAG. 
- Write ARIA labels in a “Learn more about x” format. 

Aria label content

- Use: Learn more about Visa Token Services
- Instead of: Visa Token Service: read more

- Use: Read more about biometrics
- Instead of: Read more



---

# index

---
title: Grammar and punctuation
description: Learn Visa product grammar and punctuation styles to ensure consistent experiences.
meta_description: Learn Visa product grammar and punctuation styles to ensure consistent experiences.
thumbnail: assets/content/grammar-graphic.svg
---

Grammar refers to the rules for structuring and combining words into sentences. Punctuation refers to the marks used to structure, organize, and clarify sentences. Follow these guidelines to ensure all Visa experiences are consistent, easy to understand, and accurate.
<br />
We primarily follow the [Chicago Manual of Style](https://www.chicagomanualofstyle.org/home.html)<!-- aria-label="Chicago Manual of Style (opens in a new tab)" --> for grammar, spelling, punctuation, and language usage. However, in some cases we refer to the [Associated Press (AP) Styleguide](https://www.apstylebook.com/)<!-- aria-label="Associated Press Styleguide(opens in a new tab)" -->.

## Active and passive voice
Active and passive voice refer to how a sentence is structured to highlight different parts of the action. In active voice, the subject performing the action is the main focus. This makes it easy to identify who or what is doing something. In passive voice, the action itself is the main focus, and it's not always clear who or what is doing it.

### Active voice
A sentence is in active voice when a subject, usually a person or entity like Visa, performs an action. Active voice is clear, concise, and actionable. This is the preferred method in most scenarios as it’s generally clearer, more direct, and more concise than passive voice.

How to use active voice

- Use: Add your credentials.
- Instead of: User credentials must be added.

- Use: Enter your response below.
- Instead of: Response should be entered below.

- Use: The content team regularly updates the style guide.
- Instead of: The style guide is regularly updated by the content team.

### Calls to action

A call to action (CTA) describes a [Button](https://design.visa.com/components/button/usage), [Link](https://design.visa.com/components/link/usage), or text intended to guide users toward a task or action.
<br />
CTAs should be written with command verbs to ensure it is clear what will happen when selected. Command verbs refer to descriptive verbs that give a direct order or instruction, like “Save”, “Apply”, or “Send”. The only exceptions are common navigational labels like “Next”, or “Back”. 
- Ensure all buttons include command verbs like “Save”, “Apply”, or “Send”. 
- Avoid using sensory language like “See” or “View”. For more information, reference [Inclusive language](https://design.visa.com/content/inclusive-language). 

Call to action language and context

- **Call to action (CTA) language**: Learn more<br /><br />Explore options<br /><br />Browse credit cards<br /><br />Compare products
- **Context**: Discovery or learning

- **Call to action (CTA) language**: Get started<br /><br />Find your Visa card<br /><br />Access offer<br /><br />Download pdf<br /><br />Check it out
- **Context**: General

- **Call to action (CTA) language**: Join now<br /><br />Subscribe, Subscribe and save<br /><br />Sign up
- **Context**: Newsletters

- **Call to action (CTA) language**: Learn more<br /><br />Start reading<br /><br />Begin tutorial<br /><br />Review guide
- **Context**: Product onboarding, Documentation

- **Call to action (CTA) language**: Contact us<br /><br />Chat with us<br /><br />Get help<br /><br />Connect to an expert
- **Context**: Support

- **Call to action (CTA) language**: Buy now <br /><br />Place order<br /><br />Complete purchase<br /><br />Make transfer, Transfer now<br /><br />Add to cart<br /><br />Check out
- **Context**: Transactions

- **Call to action (CTA) language**: Next<br /><br />Back<br /><br />Continue
- **Context**: Navigation

### Passive voice
A sentence is in passive voice when the subject is omitted or de-emphasized, giving the feeling that something "just happens." While products and experiences usually use active voice, passive voice can be used to soften language and sound less accusatory towards the user or Visa. This is more appropriate in sensitive cases, such as legal statements or error messages, where leaving the subject out can avoid placing blame on the user.
- Use passive voice if you notice a command, instruction, or explanation sounds too critical or accusatory. 

How to use the passive voice

- Use: The transaction was not processed due to insufficient funds.
- Instead of: You do not have enough funds to process this transaction.

- Use: Your card was declined.
- Instead of: We declined your card.

- Use: Something went wrong. Please reload the browser window.
- Instead of: You made an error.<br /><br />We made an error.

- Use: The account was not found.
- Instead of: We can’t find your account.

## Capitalization

### Sentence case
Sentence case refers to capitalizing text like it’s in a sentence: the first letter is capitalized, and everything else is lower case. Sentence case is primarily used in UX writing for products because it's more modern, readable, and "human" than title case. It's also better for globalization as title case is uncommon outside English publications.
- Use sentence case for all aspects of Visa’s product experiences, including page titles, headings, and UI elements like tooltips or tabs.

<img src="https://design.visa.com/assets/content/grammar/sentence-case-example.svg" alt="An example site banner with two callouts. A callout saying Title case (proper noun) is pointing to the Application Name text in the banner. Another callout says sentence case (all other scenarios) is pointing to a tab in the banner labelled Client dashboard."/>

### Title case

Title case refers to text that’s written with the first letter of each word capitalized. Only use title case for proper nouns, which include the names of people, places, and certain things, such as [Visa branded terms and products (internal only)](https://bookmarks.visa.com/vpds-visa-branded-terms-and-products)<!-- aria-label="Visa branded terms and products (internal only, opens in a new tab)" -->. If referring to anything trademarked or copyrighted, refer to [Fictitious brands](https://bookmarks.visa.com/vpds-fictitious-brands) for general guidance or consult with the legal or brand team for official instructions on how to proceed.

### All caps
All caps refers to text written in all capital letters. This is reserved for acronyms and initialisms, some abbreviations like file extensions, and certain text styles like overlines. 

#### Acronyms

Acronyms are terms based on the first letter of each word in a title, like VPDS for Visa Product Design System. Unless commonly understood, like PDF, acronyms should always be defined in proximity to where they’re being used, such as on the same page or within the same paragraph; for example, Visa Product Design System (VPDS). 
<br />
Be mindful that users often jump around between content and don’t read everything on a page linearly, so sometimes acronyms need to be defined multiple times within the same experience. 
- Use all capital letters for acronyms.  
- Use acronyms only after you have defined and contextualized them. For a list of Visa and industry-specific acronyms, refer to the Visa Finance [Global Sourcing Acronyms and Glossary (internal only)](https://bookmarks.visa.com/vpds-global-sourcing-acronyms-and-glossary)<!-- aria-label="Global Sourcing Acronyms and Glossary (internal only, opens in a new tab)" -->.

## Punctuation

Punctuation in products and experiences depends on use case. Follow the guidance below to ensure consistent punctuation across products and experiences. 
- Use proper punctuation for all text containing full sentences. 
- Omit end punctuation, such as periods, for all headings, titles, and UI labels. 
- Use exclamation marks sparingly, ideally no more than once per page. 

### Apostrophes

#### Contractions

Contractions are a type of abbreviation where words are shortened by omitting certain letters or sounds. These are typically created by combining two words, with the apostrophe placed where the omitted letters would’ve been. Examples of contractions include "don't" (do not), "can't" (cannot), "they're" (they are), and "it's" (it is or it has).
- Use contractions to make your content more conversational and human rather than academic or robotic. 
- Avoid using apostrophes in place of numbers or letters unless forming contractions.

Example usage of contractions

- Use: Something didn’t work.
- Instead of: Something did not work.

- Use: This feature isn’t available.
- Instead of: This feature is not available.

- Use: We’re searching for your information.
- Instead of: We are searching for your information.

- Use: 2023
- Instead of: '23

#### Possessives

Possessives in English grammar are used to indicate ownership or a close relationship. 
- Use apostrophes to show possession, such as “Visa’s products”. 
- Add ‘s for singular nouns like “Company”, even if the word ends in an s. 
- Add ‘s for plural nouns that don’t end in an s, like “Children”. 
- Add an apostrophe at the end of the word for plural nouns ending in s, such as “Cities”. 

Example usage of possessives

- Use: The company’s credit card
- Instead of: The companys credit card <br /><br /> The companies credit card

- Use: The children’s section
- Instead of: The childrens section

- Use: Several cities’
- Instead of: Several cities

### Commas
VPDS recommends oxford commas to boost clarity in written text. This refers to commas placed before the word “and” in a list or series of multiple items.
- Use the oxford (or serial) comma in all product contexts. 
- Try breaking sentences with many commas into multiple sentences to improve readability and maintain a reasonable reading level.

Example of how to use a comma

- Use: “Visa uses a sixth grade reading level, sentence case, and white space to improve readability.”
- Instead of: “Visa uses a sixth grade reading level, sentence case and white space to improve readability.”

### Colons
Colons are used to show that a clause is directly related to the one before it. 
- Use colons to introduce lists or steps in a process if the sentence is phrased as a complete thought that introduces the content to follow.
- Avoid using colons in sentences.

Examples of how to use colons

- Use: Visa uses the following conventions in all product content:
        - Oxford comma
        - Sentence case
        - 6th grade reading level
- Instead of: Visa uses the following conventions in all product content
        - Oxford comma
        - Sentence case
        - 6th grade reading level

### Semicolons
Semicolons are used to join related, independent clauses, but aren’t recommended for use in products or experiences. 
- Try simplifying sentences with a comma to avoid using semicolons.

Examples of how to use semicolons

- Use: Visa connects is a global network, connecting the world by being the best way to pay and be paid.
- Instead of: Visa connects is a global network; we connect the world by being the best way to pay and be paid.

### Ellipses
Ellipses (…) can be a useful tool in UI and product content but should be used sparingly in body content or blocks of text.

### Parentheses
Parentheses are punctuation marks used for information that’s not essential to the main point of the sentence, but provides additional context or clarification. The information inside the parentheses can be a single word, a fragment, or multiple complete sentences.
- Use parentheses for supplemental information in body copy and UI. Never use brackets in place of parentheses.

Examples of how to use parentheses

- Use: In all UI text, including titles and tooltips, use sentence case (as opposed to title case).
- Instead of: In all UI text, including titles and tooltips, use sentence case [as opposed to title case].

- Use: Loading… (55% complete)
- Instead of: Loading… [55% complete]

## Symbols

Symbols shouldn’t be used in place of words like “and”, “or”, or “at”. This includes ampersands (&) or plus signs (+) in place of the word “and”, number signs (#) in place of the word “number”, at signs (@) in place of the word “at”, and slashes (\ or /) and the word “slash” in place of the the words “or,” or “and”. 
- Avoid using symbols in place of written words in copy. The only exception is businesses, products, or teams whose names already include symbols, such as Design @ Visa. 

Examples of how to use symbols

- Use: Pause your card at the touch of a button.
- Instead of: Pause your card @ the touch of a button

- Use: Save and quit
- Instead of: Save & quit

- Use: Terms and conditions
- Instead of: Terms + conditions

- Use: Enter your phone number.
- Instead of: Enter your phone #.

- Use: Your available balance is your current balance minus any pending charges.
- Instead of: Available balance = current balance – pending charges

### Icons
Text symbols should never be used in place of any Visa icon, no matter how closely they appear in resemblance. Always use the proper Visa-branded or generic icons. Learn more by visiting [Design kits](https://design.visa.com/designing/design-kits).

### Asterisks
Asterisks (*) are used to indicate a source citation (or footnote), an omission, and to point to a disclaimer or comment. The most common use case are disclaimers for products. 
- Use the asterisk after every punctuation mark except for dashes. In the case of dashes, place the asterisk before the dash. It’s not necessary to end the disclaimer with an asterisk as you would with a quote.
- Remove spaces before and after an asterisk.
- Never use asterisks to censor inappropriate language. Instead, curse words and violent language should not be used.  

Examples of how to use asterisks

- Use: Please enter your CVV number*<br /><br />*A CVV, or card verification value, is typically a three- or four-digit number found on a credit card.
- Instead of: Please enter your CVV* number<br /><br />\*Your CVV number is found on the back of your card and is typically 3 numbers.\*

## Dashes and hyphens

Em dashes, en dashes, and hyphens are distinct punctuation elements that are commonly misused. They can be entered in Microsoft Word from the Special Characters tab within the Advanced Symbols section in the Ribbon.
<br />
Keyboard shortcuts work in Microsoft Word and other software, like Figma. Refer to the following table for a quick guide on manually entering these characters in text.

Examples of how to use dashes

- Element: minus (-)
- MacOS: minus (-)

- Element: Option and minus (-)
- MacOS: Alt + type 0150 (use num lock)

- Element: Shift + Option + minus (-)
- MacOS: Ctrl + Alt + minus (-)

### Hyphens
Hyphens (-) are punctuation marks used to join words or parts of words together. 
- Remove spaces before or after hyphens.
- Use a hyphen to combine two words when they come before a noun, not after. 
- Always spell out common fractions and hyphenate them. 

Examples of how to use hyphens

- Use: One-half of the pizzas are gone.
- Instead of: 1/2 of the pizzas are gone.

- Use: The interfaces are user friendly.
- Instead of: The interfaces are user-friendly.

- Use: User-friendly interfaces
- Instead of: User friendly interfaces

### En dashes
En dashes (–) are punctuation marks that are slightly longer than a hyphen (-) but shorter than an em dash (—). They’re typically used to indicate a range of values in place of the word "to" or to denote a connection or a conflict between two concepts.
- Remove spaces before or after hyphens.
- Use en dashes (–) to relate one concept to another.
- Avoid using an en dash instead of the words “from”, “to”, or “between” to introduce number ranges.

Examples of how to use En dashes

- Use: Set focus mode on your phone from 8 AM to 5 PM.
- Instead of: Set focus mode on your phone from 8 AM–5 PM.

- Use: Communication is important for establishing designer–developer collaboration.
- Instead of: Communication is important for establishing designer/developer collaboration.

### Em dashes
Em dashes (—) are the longest type of dash. They’re used in place of commas, colons, semi-colons, or parentheses to emphasize information.
- Remove spaces before or after hyphens. 
- Use em dashes to separate additional, unessential information from the rest of the sentence. 
- Use em dashes to separate distinct, related thoughts. 

Examples of how to use Em dashes

- Context: Avoid using punctuation in UI labels—except for apostrophes or internal punctuation—to maintain a friendly tone and improve readability.

- Context: Enabling these security features for cardholders can reduce the number of false disputes  issuers have to resolve—in other words, everybody wins.

## Abbreviations
In product content, it’s generally best to avoid uncommon or unnecessary abbreviations where possible. Instead, spell out terms to increase the clarity and legibility of your content. Refer to the [Chicago Manual of Style](https://www.chicagomanualofstyle.org/book/ed17/backmatter/index/a.html)<!-- aria-label="Chicago Manual of Style (opens in a new tab)" --> for a detailed list of abbreviations.

### Honorifics and titles
Honorifics and titles are formal styles used to denote professional positions, academic qualifications, or certain family relationships. They can be prefixes, like "Dr.", "Prof.", or "Mr.", which are added before a person's name, or suffixes, like "Jr.", "Sr.", or "Ph.D.", which are added after a person's name.
- Avoid using English honorifics or social title abbreviations such as “Ms.”, “Mrs.”, or “Mr.” to reduce assumptions where gender identity or marital status are unknown.
- Capitalize the first letter and include a period and a space between title abbreviations and names, such as “Mr. Alex Miller.”
- Capitalize and omit periods for academic degrees, placing them after the name with a comma and space, such as “Alex Miller, PhD.”

### Latin abbreviations
- Avoid using abbreviations with Latin or Greek root words to increase clarity. 
- Rephrase these terms to be more inclusive of non-native English speakers whose first languages have not adopted widespread use of these abbreviations.

Examples of how to use Latin abbreviations

- Use: For example,
- Instead of: e.g.,

- Use: For now<br /><br />Temporarily
- Instead of: pro tem.

- Use: In other words,<br /><br />More specifically,
- Instead of: i.e.,

- Use: Now<br /><br />Immediately<br /><br />Right away
- Instead of: stat.

#### Exceptions

Although plain language is the general standard for the UX industry, some Latin terms and abbreviations frequently appear in business, corporate, and research contexts. 
- Consider the needs of your users based on localization requirements if you choose to include these terms.

Exeptions and context for using Latin abbreviations

- Term: “when necessary”<br /><br />For a certain or special purpose requiring your attention
- Meaning: Job postings, descriptions, requirements

- Term: et cetera<br /><br />“and the others” (inanimate objects)
- Meaning: Lists

- Term: et alia<br /><br />“and others” (people)
- Meaning: Academic papers, authors, citations

- Term: curriculum vitae<br /><br />Document detailing a person’s work experience and education
- Meaning: Job applications or postings

- Term: “after the event”
- Meaning: Statistics, scientific tests, logical fallacy

- Term: in re<br /><br />“in the matter of” or “concerning”
- Meaning: Email subject lines

- Term: versus<br /><br />“against”
- Meaning: Court cases, sports games

### Date and time abbreviations
Abbreviations are commonly used to express compact versions of time when space does not permit full versions. Learn more about formatting in [Date and time](https://design.visa.com/content/grammar/#date-and-time).

#### Days of the week

When space is limited, days may be expressed using the standard three or four letter abbreviation. 
- Capitalize the first letter of the abbreviation. 
- Remove punctuation unless grammatically necessary for the sentence.

Example usage of days of the week

- Use: Sun, Mon, Tues, Wed, Thurs, Fri, Sat
- Instead of: S, M, T, W, Th, F, Sa

#### Months

When space is limited, months may be expressed using the standard three letter abbreviation. 
- Capitalize the first letter of the abbreviation. 
- Remove punctuation unless grammatically necessary for the sentence.

Examples usage of months

- Use: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
- Instead of: J, F, M, A, M, J, J, A, S, O, N, D.

#### Time of day

Use AM/PM to indicate the time of day when using 12-hour time notation. Learn more about formatting in [Date and time](https://design.visa.com/content/grammar/#date-and-time).
- Capitalize both letters of the abbreviation. 
- Remove punctuation unless grammatically necessary for the sentence. 

Example usage of times of day

- Use: 12 AM
- Instead of: 12am, 12 a.m.

- Use: 12 PM
- Instead of: 12pm, 12 p.m.

### Time zones
Time zones are typically expressed using two or three uppercase letters, usually within parentheses.
- Capitalize all letters of the abbreviation. 
- Include the abbreviation in parentheses following the time. 
- Include a space before the zone abbreviation. 
- Remove the S (for Standard) or D (for Daylight) if your users are in a single time zone.
- Include an S (for Standard) or D (for Daylight) if your users are in a combination of time zones. 

Example usage of time zones

- Use: 5:00 PM (PT)
- Instead of: 5:00 PM (PDT)

- Use: 6:30 AM (CST)
- Instead of: 6:30 AM (cst)

### Units
Units are standards for expressing and measuring quantities. They help specify the amount, size, or degree of something within a specific measurement system.
- Include a space between the last digit of the numerical value and the unit abbreviation.
- Avoid pluralizing or adding periods after the unit of measurement unless needed to end the sentence or distinguish the unit from other words.

Example usage of units

- Use: 12 oz
- Instead of: 12 oz.

- Use: 45 lb
- Instead of: 45 lbs

- Use: Use 24 px margins.
- Instead of: Use 24 px. margins.

#### Units of measurement

The following tables shows commonly-used units of measurement in product or UX contexts.

Example usage of units of measurement

- Unit: Kilobytes<br /><br />Gigabytes<br /><br />Terabytes
- Abbreviation: KB<br /><br />GB<br /><br />TB
- Context: Storage size

- Unit: Pixels<br /><br />Megapixels<br /><br />Pixels per inch<br /><br />Point<br /><br />Density-independent pixels/dots per inch
- Abbreviation: px<br /><br />MP<br /><br />ppi<br /><br />pt<br /><br />dpi
- Context: Graphics

- Unit: Centimeters<br /><br />Meters<br /><br />Inches<br /><br />Feet
- Abbreviation: cm<br /><br />m<br /><br />in<br /><br />ft
- Context: Length

- Unit: Grams<br /><br />Kilograms<br /><br />Ounces<br /><br />Pounds
- Abbreviation: g<br /><br />kg<br /><br />oz<br /><br />lb
- Context: Weight

#### Units of time

Units of time may be expressed as abbreviations when there are space limitations.
- Spell out these units where possible instead of using abbreviations. 

Example usage of units of time

- Use: second
- Instead of: sec

- Use: minute
- Instead of: min

- Use: hour
- Instead of: hr

- Use: day
- Instead of: d

- Use: month
- Instead of: mo

- Use: year
- Instead of: yr

## Date and time

### International notation
Visa follows [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)<!-- aria-label="ISO 8601 (opens in a new tab)" -->, the international standard maintained and governed by the International Organization for Standardization (ISO) in Geneva. To promote accuracy and prevent error, it’s used to standardize dates and times in product development, especially in back-end programming.
<br />
When indicating date and time in user-facing scenarios, select a formatting method based on regional conventions and user expectations. If your product serves a range of countries, use international notation as determined by IOS 8601. 

### Regional notation
Throughout most of the world, date formatting follows ISO 8601. However, regional differences exist. Use the tables below to help determine the appropriate formatting for your use case and audience.

#### Date formatting

Date formatting differs by region. Use the table below to help determine the appropriate time formatting for your use case and audience.

Types of date format by country

- Majority of world countries: Day month, year<br /><br />2 January, 2023<br /><br />dd-mm-yyyy<br /><br />02-01-2023
- China, Japan, North Korea, South Korea, Taiwan,<br /> Hungary, Mongolia, Lithuania, Bhutan, and ISO 8601: Year, month day<br /><br />2023, January 2<br /><br />yyyy-mm-dd<br /><br />2023-01-02
- United States and territories: Month day, year<br /><br />January 2, 2023<br /><br />mm-dd-yyyy<br /><br />01-02-2023

#### Time formatting

Time formatting differs by region. Use the table below to help determine the appropriate time formatting for your use case and audience.

Time format by country

- Majority of world countries and ISO 8601: 24-hour format:<br /><br />hh:mm:ss<br /><br />13:02:03<br /><br />hh.mm.ss.sss<br /><br />13:02:03:674
- United States and territories, the Commonwealth: 12-hour format:<br /><br />hh:mm:ss AM or PM<br /><br />01:02:03 PM<br /><br />hh.mm.ss.sss AM or PM<br /><br />01:02:03:674 PM
- The United Kingdom: Both 24 and 12-hour formats

## Numbers
Numbers are often formatted differently depending on the context. When formatting manually, be mindful of how the number appears in written text, when to truncate, what character (decimal or period) is used as the thousands separator, and how negative numbers are displayed.
- Use numerals for numbers 10 and above in written text and spell out numbers nine and below. This doesn’t apply to other formats like tables, or for precise units of measurement under 10.
- Use commas for numbers with four or more digits.
- Use en dashes between numbers without spaces to indicate a range.
- Use hyphens between groups of numbers, such as in phone numbers. Avoid using parentheses, spaces, or periods to separate numbers if possible, however there may be regional variations.
- Use the + sign before the country code when listing phone numbers for specificity.

Number format examples

- Use: Fintech is one of the fastest growing industries, with the market estimated at roughly $112.5 billion in 2021, with an expectation of reaching $332.5 billion by 2028 according to Globenewswire.com.
- Instead of: Fintech is one of the fastest growing industries, with the market estimated at roughly one hundred twelve billion five hundred million dollars in 2021, with an expectation of reaching three hundred thirty two million five hundred million by 2028 according to Globenewswire.com.

- Use: Visa initiated business with seven more partnering firms in July 2022.
- Instead of: Visa initiated business with 7 more partnering firms in July 2022.

- Use: Visa’s stock went up by 2.34 cents in the last minute.
- Instead of: Visa’s stock went up by two point thirty four cents in the last minute.

- Use: 15,000<br /><br />6,948
- Instead of: 15k<br /><br />6948

- Use: 0.00–49.99
- Instead of: 0.00–49.99<br /><br />0.00-49.99<br /><br />0.00 — 49.99

- Use: +1-347-555-0100<br /><br />+1-347-555-0100
- Instead of: 347.555.0100<br /><br />1-(347) 555-0100

### Negative numbers
Negative numbers can be formatted differently depending on the context or language. In written sentences, it is generally a good practice to use the symbol rather than spelling out the word "negative."
- Follow local best practices.
- Use the negative symbol without adding a space between the symbol and value.
- Use parentheses or brackets without adding spaces between the symbol and the amount.
- Avoid combining negative signs and parentheses or brackets.
- Apply the color red only with the appropriate negative symbol, parentheses, or bracket.

Negative number format examples

- Use: -23<br /><br />23-
- Instead of: - 23<br /><br />23 -

- Use: (23)<br /><br />[23]
- Instead of: ( 23 )<br /><br />( 23 )

- Use: -23 or 23-<br /><br />(23) or [23]
- Instead of: -(23)<br /><br />-[23]

- Use: Note: text in this cell is in a red font<br/><br/>-23<br /><br />23-<br /><br />(23)<br /><br />[23]
- Instead of: Note: text in this cell is in a green font<br/><br/>-23<br /><br />23-<br /><br />(23)<br /><br />[23]

### International currencies
Currencies are expressed differently across the world. [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html)<!-- aria-label="ISO 4217 (opens in a new tab)" --> is the recognized international standard for representing currencies. Currencies can be represented both numerically and alphabetically, using either three digits or three letters. The alpha code uses the first two letters of the [ISO 3166-1 alpha-2](https://www.iso.org/iso-3166-country-codes.html)<!-- aria-label="ISO 3166-1 alpha-2 (opens in a new tab)" --> country code and the initial of the country’s main currency unit for the third letter.  

#### General

- Place uppercase country codes before or after the amount.
- Add a space between the country code and the value.
- Insert an en dash between numerals to indicate a monetary range followed by the country code.
- Avoid spelling out currencies or currency codes.
- Shorten amounts over 999,999 (million, billion, trillion, or M, B, T).

Example formats for currency

- Use: 10 USD<br /><br />USD 10
- Instead of: usd 10<br /><br />10 usd

- Use: 30M CAD
- Instead of: 30CAD

- Use: 15–20 CAD
- Instead of: 15-20 CAD<br /><br />15—20 CAD

- Use: 50 AUD
- Instead of: Fifty AUD<br /><br />Fifty Australian Dollars

- Use: 30 million EUR<br /><br />30M EUR
- Instead of: 30,000,000 EUR

#### Symbols and decimals

When formatting currencies with symbols and numbers, consider the following locale-sensitive elements:
- Use the country’s [assigned currency symbol](https://www.xe.com/symbols/)<!-- aria-label="assigned currency symbol (opens in a new tab)" -->. 
- Avoid adding a space between symbols and numerals unless local guidelines dictate.
- Place the symbol before or after the numeral, following local guidelines.
- Follow local guidelines to determine whether to use commas or periods when expressing decimals. For example, in the United States, this character is a period (.). In Germany, it is a comma (,). So, two thousand fifty-five and eight-tenths are displayed as 2,055.8 in the United States and 2.055,8 in Germany.
- Use an en dash between numerals to indicate a monetary range and include the symbol before all numerals to avoid mistaking the dash for a decimal.
<br />
The following chart shows commonly-used currencies and their formats:

Example format with columns for currency, locale, with symbol, and without symbol and code.

- Currency: en-US
- Locale: $15.50
- With symbol: $15.50 USD

- Currency: en-CA<br /><br />fr-CA
- Locale: $15.50<br /><br />15,50 $
- With symbol: $15.50 CAD<br /><br />15,50 $ CAD

- Currency: en-AU
- Locale: $15.50
- With symbol: $15.50 AUD

- Currency: de-DE, fr-FR<br /><br />en-IE<br /><br />nl-NL
- Locale: 15,50 €<br /><br />€15.50<br /><br />€15,50
- With symbol: 15,50 € EUR<br /><br />€15.50 EUR<br /><br />€15,50 EUR

- Currency: en-GB
- Locale: £15.50
- With symbol: £15.50 GBP

- Currency: ja-JP
- Locale: ¥1550
- With symbol: ¥1550 JPY

- Currency: en-NZ
- Locale: $15.50
- With symbol: $15.50 NZD

- Currency: zh-HK
- Locale: $15.50
- With symbol: $15.50 HKD

- Currency: zh-SG
- Locale: $15.50
- With symbol: $15.50 SGD

- Currency: da-DK
- Locale: 15,50 kr.
- With symbol: $15.50 USD kr. DKR

<br />
*When presenting multiple currencies in the same context or presenting unfamiliar currencies, use the currency’s country code along with the symbol. For example, CAD and USD both use $.

## Pronouns
- Avoid using first-person pronouns like “we” or “us” within products. The user is less concerned with the authors of the experience and more concerned about completing tasks. 
- Use second-person pronouns by referencing the reader as “you,” especially when giving instructions. Using “you” whenever you want to imply an action on the user’s part can help clarify where their involvement is required.
- Follow best practices outlined in [Inclusive language](https://design.visa.com/content/inclusive-language) when using third-person pronouns. 

## Lists
Lists can be phrased and formatted in a variety of ways. Regardless of how you phrase or punctuate lists, ensure it’s consistent across list items or instances in your experience.
- Use consistent verb patterns and punctuation when making lists in sentences. 
- Start a list of bullets with verbs or nouns and aim for the same  length. 
- Punctuate all sentences, bullets, or lists consistently. 

### List type
Consider overall structure and the individual relationships between items when creating lists. This will help you determine which list construct is most appropriate for your content.

#### Bulleted lists

Lists of items with no successive relationship should use a bulleted structure but may still contain hierarchy or levels. Consider using a [Checkbox](https://design.visa.com/components/checkbox/usage) if list items are tasks or actions.

<img src="https://design.visa.com/assets/content/grammar/grammar-bulleted-lists.svg" alt="Two side by side list examples. The first is a Dinner ideas bulleted list. The first list item is Leftovers, with a nested list of two dinners. Then is a Takeout list item with a nested list three dinners. The second list is a To-do list that uses checkboxes instead of bullets."/>

#### Lettered lists

Use letters to indicate distinct parts, like for denoting figures or labeling components of diagrams.

<img src="https://design.visa.com/assets/content/grammar/grammar-lettered-lists.svg" alt="An anatomy diagram of a component using letters to label its parts and a corresponding list explaining each part's requirements. Callout A indicating the required brandmark in the footer for branding; logo and can link to homepage. Callout B the copyright text in the footer with its symbol, year of creation, author's name, and rights statement. Callout C indicating link components direct to legal content for user viewing." />

#### Numbered lists

Only use numbers and ordinals (1st, 2nd, 3rd; first, second, third, etc.) when indicating succession, order, chronology, or procedure. If these terms must be used, spell them out where possible to avoid using the number format, as some text editors and processors don’t support superscripts.

<img src="https://design.visa.com/assets/content/grammar/grammar-numbered-lists.svg" alt="An Instructions list where each step is in a numbered list."/>

### List punctuation
Only use end punctuation in lists when the list item is a complete sentence. If complete sentences are used in a list, ensure all list items are full sentences. Do not break structure by mixing full sentences and fragments.

Examples of punctuation in a list

- Use: Visa uses the following conventions in all product content:
        - Oxford comma
        - Sentence case
        - 6th grade reading level
- Instead of: Visa uses the following conventions in all product content:
        - Use an oxford comma
        - Sentence case
        - Write at a 6th grade reading level?

- Use: In all product content:
        - Use oxford commas.
        - Use sentence case.
        - Write at a 6th grade reading level.
- Instead of: In all product content:
        - Use oxford commas
        - Sentence case.
        - Can you write at a 6th grade reading level?

## Parallel structure
Parallel structure means using the same pattern of words to show that two or more ideas have the same level of importance. In the product context, this is accomplished by using consistent sentence and language structure throughout your content. This uniformity helps users more easily form mental models of the interface and navigate intuitively.

Examples of parallel structure

- Use: Accounts | Transactions | Services | Profile
- Instead of: Accounts | Make a transaction | Services | Update profile

- Use: We’re using the power of our network to **create** new solutions, **stimulate** investments, and **promote** usage.
- Instead of: We’re using the power of our network to **create** new solutions, **stimulating** investments, and **promote** usage.

- Use: **Step 1: Diagnose**<br /><br />

        **Step 2: Align**<br /><br />

        **Step 3: Roadmap**<br /><br />
    
        **Step 4: Implement**
- Instead of: **Step 1: Diagnose your problem**<br /><br />

        **Step 2: Insight alignment**<br /><br />

        **Step 3: Roadmap**<br /><br />

        **Step 4: Start implementing**

- Use: - **Use** expertise, data, and benchmarking to uncover opportunities
          - **Validate** the findings to align on approach to drive business forward
          - **Create** a comprehensive roadmap to get you to where you want to be in the future
          - **Turn** process into action with VCA Managed Services that drive innovation
- Instead of: - **Use** expertise, data, and benchmarking to uncover opportunities
          - **You'll** get findings to align on approach to drive business forward
          - **Creating** a comprehensive roadmap can help get you to where you want to be in the future
          - **By turning** process into action with VCA Managed Services you’ll drive innovation

- Use: Visa leadership principles:
        - We lead by example
        - We communicate openly
        - We enable and inspire
        - We excel with partners
        - We act decisively 
        - We collaborate
- Instead of: Visa leadership principles:
        - Lead by example!
        - We communicate openly.
        - Enable and inspire
        - Can your skills help partners excel?
        - Act decisively... 
        - and collaborate.



---

# index

---
title: Inclusive language
description: Gain insight into the use of inclusive language to ensure Visa products include everyone, everywhere. 
meta_description: Gain insight into the use of inclusive language to ensure Visa products include everyone, everywhere.
thumbnail: assets/content/inclusive-language-graphic.svg
header_image: assets/content/inclusive-lang-overview.svg
---

Inclusive language refers to language that's respectful of all people regardless of gender, race, ethnicity, age, ability, or any other aspect of identity. For Visa to serve everyone, everywhere, we need to represent and speak to everyone, everywhere.

## Best practices 
- **Reference identity with caution:** Ensure references to demographics, identity characteristics, or group membership is essential and relevant before including. When in doubt, opt for neutral language that applies to everyone. 
- **Use accurate terms and phrases:** Always seek guidance from subject matter experts or representatives of the group you're referencing to confirm the appropriate language, terms, or phrases to use.
- **Prioritize people-first language:** Avoid labeling individuals, and when you find you must reference their group membership, acknowledge their humanity first.
- **Collect identity data sparingly and responsibly:** While it can ensure experiences relevant and accessible, always collaborate with the legal team before asking users for such information.

<div class="v-flex v-flex-col v-gap-24 v-mt-48">
<SectionMessage messageType="subtle">

<Typography variant="body-2-bold">Collect data with caution</Typography>

Consult Legal to ensure applicable laws don't prevent collecting or using demographic information.
</SectionMessage>
</div>

### Personally identifiable information (PII)

Personally identifiable information (PII) includes unique identity characteristics that can be used to identify an individual, particularly when combined with other non-sensitive data. This includes full name, social security number, government-issued identification number, mailing or residential address, driver's license number, bank account number, passport number, or email address.

- Only collect PII when it's essential. 
- Consult with your designated legal representative before collecting PII in Visa apps or experiences. 
- Consider local laws pertaining to certain states, provinces, countries, and regions. Failure to comply can result in Visa and our partners risking fines and violations.

#### Collecting identity characteristics

Identity characteristics refer to personal attributes such as gender, race, and ethnicity that define an individual's identity. 
- Only ask for these characteristics when it is immediately relevant to the product or experience or provides you with meaningful information to improve the experience for all users.
- Include the option to select multiple items to enable users to accurately represent themselves.
- Always include options such as “Prefer to self-describe” if collecting this information is essential to your product or experience. 
- Avoid including items such as “other”, as it doesn't provide useful data and implies the identities not represented are less important than those that are.  If your product can't accommodate custom input, consider including “Not listed”
<br/>
**Note:** Some of the terms used below, such as those under “Race”, follow standards set by the US government, not Visa. Always confirm the most up-to-date language before collecting identity characteristics, and ensure they reflect the best practices established by your product's region or locale.

Terms for gender identity characteristics

- Use: Gender identity (with option to check multiple items):
        - Non-binary
        - Transgender woman 
        - Transgender man 
        - Cisgender woman
        - Cisgender man
        - Prefer to self-describe (with form) OR Not listed
        - Prefer not to disclose
- Instead of: Sex:
        - Male
        - Female
        - Intersex
        - Other

- Use: Pronouns (with option to check multiple items): 
        - He/him/his
        - She/her/hers
        - They/them/theirs
        - Prefer to self-describe (with form) or Not listed
        - Prefer not to disclose
- Instead of: Pronouns: 
        - She/her/hers
        - He/him/his
        - Other

- Use: Sexual orientation (with option to check multiple items):
        - Gay
        - Lesbian
        - Bisexual
        - Queer
        - Asexual
        - Straight/heterosexual
        - Prefer to self-describe (with form) OR Not listed
        - Prefer not to disclose
- Instead of: Sexual orientation:
        - Straight/heterosexual
        - Gay
        - Other

- Use: Race (with option to check multiple items):
        - White or caucasion (Not Latinx or Hispanic)
        - Latinx or Hispanic
        - East Asian (Not Latinx or Hispanic)
        - Black or African American (Not Latinx or Hispanic)
        - Native Hawaiian or Pacific Islander (Not Latinx or Hispanic)
        - Asian – Not listed (Not Latinx or Hispanic)
        - Southeast Asian (Not Latinx or Hispanic)
        - Middle Eastern or North African (Not Latinx or Hispanic)
        - American Indian or Alaska Native (Not Latinx or Hispanic)
        - Prefer not to disclose
- Instead of: Race
        - Asian
        - Black
        - Indigenous
        - White 
        - Other

- Use: Relationship status (with option to check multiple items):
        - Single
        - Married
        - Unmarried partner
        - Registered domestic partner
        - Widowed
        - Divorced
        - Separated
        - Prefer to self-describe
- Instead of: Relationship status:
        - Single
        - Married
        - Widowed
        - Separated
        - Divorced

### People-first language
People-first language refers to terms and phrases that emphasize someone's humanity before their condition or group membership. In contrast, deficit-based language focuses on what people lack rather than what they possess. In general, avoid deficit-based language and reframe your language to focus on achievements instead. If you must mention a deficit or lack, do so with sensitive language.
- Describe the attribute(s) of a person or group as a secondary feature or characteristic, rather than using the attribute as the primary descriptor.

<div class="v-flex v-flex-col v-gap-24 v-mt-48">
<SectionMessage messageType="subtle">
<Typography variant="body-2-bold">People-first language is not universal</Typography>

While we generally align to people-first language when writing content in product interfaces, not all people prefer people-first language. Identity-first language is an alternative that places the descriptor first and is most common in specific communities. Ask individuals how they want to be referred to.
</SectionMessage>
</div>

Example usage of people-first terms

- Use: Completed x years of high school
- Instead of: High school dropouts

- Use: People without a high school diploma<br/><br/>
        People without formal education
- Instead of: Poorly educated<br/><br/>
        Having little education

- Use: Neighborhoods/communities with high poverty rates
- Instead of: Inner-city<br/><br/>
        Disadvantaged

- Use: Opportunity gap
- Instead of: Achievement gap

### Universal language
Universal language means writing so everyone, everywhere can understand. As Visa connects businesses, banks, and governments in over 200 countries and territories, it's crucial to ensure products and experiences are usable to everyone they reach.<br/><br/>
**Note:** While many Visa products reach global audiences, there are specific use cases for localization. If an experience is designed to target a specific audience or user in only one specific geographic region, the messaging can be localized to match their language, lexicon, culture, grammar, and UX/UI conventions. 

## Psychographics 

Psychographics are psychological attributes that describe people's attitudes and aspirations, usually used in reference to market research. These include values, lifestyle, attitudes and opinions, spending habits, and interests. Inclusive writing about psychographics means no user feels excluded based on these traits.

- Represent a diverse variety of lifestyles in imagery and examples to help people visualize themselves in association with Visa products. Use the [Visa Brand Identity Asset Library Photography Guidance (internal only)](https://bookmarks.visa.com/vpds-visa-brand-identity-asset-library-photography-guidance)<!-- aria-label="Visa Brand Identity Asset Library Photography Guidance (internal only, opens in a new tab)" --> for help selecting imagery.

## Demographics

Demographics refer to attributes like gender identity, orientation, relationship status, race, religion, age, and socioeconomic status. Inclusive language ensures that regardless of demographics, all users feel represented, welcome, and can understand and relate to content.

### Ability 

When writing about ability, it's important to avoid ableist language. A more respectful and inclusive approach is to use people-first language. Ableist language, while often unintentional, can inadvertently devalue individuals with disabilities. It tends to undermine their individuality, equality, and dignity. For example, say “person with a disability” instead of “disabled person”. To learn more, visit [People-first language](https://design.visa.com/content/inclusive-language/#people-first-language).

#### Non-sensory guidance

Sensory guidance refers to instructions that use senses to describe actions or behaviors, such as “read” or “view”. Many metaphorical phrases contain insinuations that may not be inclusive of or are offensive to people with disabilities.
- Avoid using sensory language anywhere in product copy, especially for buttons, links, or calls to action. 

#### Othering and reductive terms

Othering terms might insinuate there's something wrong with anyone or anything that isn't “typical”.
<br/>
**Note:** Disabled is a valid state for HTML elements, but isn't appropriate for describing overall feature functionality.

### Age
Ageism is stereotyping or discriminating against individuals or groups based on age. Ageism can take many forms and is often unintentional or subtle.
- Be intentional with your language when talking about age to avoid ageist implications.
- Avoid language that “others” certain populations by segmenting them into one group. 

### Gender, gender identity, and orientation
Any common phrases that are used to refer to everyone are gendered as masculine, like “man hours.” When discussing gender, pronouns, and orientation, use language that's accurate, descriptive, and prioritizes neutrality wherever possible.
- Avoid using masculine-gendered phrases like “man hours” 
- Omit pronouns unless they're explicitly relevant to the use case. 
- Use neutral phrasing like “they” when unsure of the correct pronouns.

### Race and ethnicity
Race and ethnicity are not synonymous and refer to distinct characteristics. While race refers to physical differences that groups and cultures consider socially significant, ethnicity refers to cultural characteristics like language, ancestry, and beliefs. Only reference race and ethnicity if it's immediately relevant.
- Be specific whenever possible to avoid grouping individuals who identify differently from each other. 
- Use “Black, Indigenous, Hispanic, Asian, and other people of color” if you must broadly reference groups other than non-Hispanic white.
- Capitalize group titles such as “Asian” rather than “asian”. 
- Avoid figurative language that equates white with positive and black or dark with negative, like “blacklisted”.
- Avoid phrases that reference race or race histories whenever possible, such as using “built-in feature” over “native feature”.

### Religion and culture
Many common phrases have origins that are not religiously inclusive or inappropriately reference specific cultures. 
- Avoid references to religion whenever possible and opt for neutral phrases to ensure all users are represented. 

## Firmographics: Writing about the industry
Firmographics are descriptive attributes used by B2B organizations to identify their target market and ideal customers. These may include industry, location, size, status or structure, and performance. These attributes contribute to the full picture that product designers and partners can consider to ensure they're mindful of stereotypes about business performance.
- Always use neutral language when describing businesses organizations, regardless of their size or performance.
- Use the table below to determine the appropriate phrasing and designation for organizations of various sizes. 
<br/>
**Note:** The following table outlines how business are classified in the United States based on size and revenue. These classifications may not apply in all countries. Always consult local guidelines to ensure you reference businesses accurately.

Neutral terms for company size, revenue, and industry

- Attribute: Company size can vary within industry and country, but generally, there are three categorizations based on number of employees: 
        - **Small business:**<br/>1,500 employees or less
        - **Mid-size or mid-market enterprise:**<br/>1,500 to 2,000 employees
        - **Large enterprise:**<br/>Over 2,000 employees<br/><br/>

        It's easy to make assumptions about businesses of various sizes, which means it's important to mitigate bias when it comes to companies of a specific size and the employees that work for them. One assumption that is often made about large enterprises is that they might be outmoded in their approach or might be slow-moving. Large businesses can be very innovative, take risks, and be disruptive! Companies of different sizes have varying needs, so there is no one-size-fits-all approach.

- Attribute: Company size can vary within industry and country, but generally, there are three categorizations based on revenue: 
        - **Small business:**<br/>$38.5 million in revenue
        - **Mid-size or mid-market enterprise:**<br/>$38.5 million to $1 billion in revenue
        - **Large enterprise:**<br/>Over $1 billion in revenue<br/><br/>
        
        It's easy to make assumptions about businesses of various sizes, which means it's important to mitigate bias when it comes to companies of a specific size and the employees that work for them. For example, there is an assumption that small businesses are typically comprised of struggling individuals working in less than ideal conditions. Small businesses comprise the majority of the world's businesses and can make a maximum of $38.5 million annually. Companies of different sizes have varying needs, so there is no one-size-fits-all approach.

- Attribute: Our biases can affect our perspective on businesses of varying industries. For instance, the bias that the engineering industry is exclusively for men or that education is for women might promote an affinity bias that inhibits these industries from hiring more diverse candidates (of course, any gender of individual can belong to any one of these industries). Every business is unique and has individual needs and approaches.<br/><br/>Visa is a financial services and technology company. We often target and work with these industry subtypes: 
        - Fintechs
        - Merchants
        - Inquirers
        - Issuers



---

# index

---
title: Content
description: Explore our content guidelines to craft thoughtful and consistent interface content for a well-designed user experience.
thumbnail: assets/home/content-graphic.svg
meta_description: Explore our content guidelines to craft thoughtful and consistent interface content for a well-designed user experience.
page_size: large
show_table_of_contents: false
---

<ContentGrid />


---

# index

---
title: Information architecture
description: Identify the best organizational structure based on page types and user needs.
meta_description: Learn how to structure, label, and organize content based on page types and user needs.
thumbnail: assets/content/ia/information-architecture-graphics.svg
related:
  components:
    - anchor-link-menu
    - horizontal-navigation
    - navigation-drawer
  patterns:
    - application-layouts
---

Information Architecture (IA) is the practice of organizing, structuring, and labeling content in an effective and understandable way. IA involves creating a clear and logical framework that helps users understand where they are and how to find what they’re looking for. Integrating IA early-on in the design process lays the groundwork for smooth and intuitive product experiences.

## Best practices
- Design simple, intuitive, and consistent navigation, avoiding unnecessary complexity.
- Offer meaningful choices to users, keeping the options limited and focused to avoid overwhelming them.
- Organize content logically and progressively. Learn more about [Progressive disclosure](https://design.visa.com/content/information-architecture/#progressive-disclosure).
- Regularly test, iterate, and document IA thoroughly.
- Use clear, consistent, descriptive labels to help users quickly identify and scan for information.
- Treat content as living items that change over time, have specific actions, and need to be managed and updated.
- Provide multiple ways to browse and search content, accommodating different mental models and preferences.

## Components of information architecture

### Organization systems
Organization systems are methods used to categorize and structure content so it’s easy to understand, navigate, and retrieve. They help create a logical flow and hierarchy within the content. There are three organization systems: sequential, hierarchical, and matrix.

#### Sequential

Sequential organization systems arrange content in a linear, step-by-step flow, guiding users through a predefined path. This method is particularly useful for processes or tasks that must be completed in a specific order, such as onboarding tutorials or checkout procedures. By presenting information in a sequence, users can easily follow along and understand each step, ensuring a smooth and logical progression.

<img src="https://design.visa.com/assets/content/ia/sequential.svg" alt="Graphical representation of a single-tier tree diagram showing one row of blocks"/>

#### Hierarchical

Hierarchical organization systems structure content in a tree-like format with parent-child relationships, creating a clear path from general to specific information. This approach is suitable for complex information where categories and subcategories help users drill down to locate specific content.

<img src="https://design.visa.com/assets/content/ia/hierarchical.svg" alt="Graphical representation of a single-tier tree diagram showing multiple rows of blocks under each branch"/>

#### Matrix

Matrix organization systems allow content to be accessed through multiple pathways, providing users with various ways to navigate and find information. This system is particularly useful for content that can be logically categorized in more than one way. By offering multiple access points, this approach caters to different user preferences and mental models, enhancing the overall user experience.

<img src="https://design.visa.com/assets/content/ia/matrix.svg" alt="Graphical representation of a diagram showing different blocks connected to each other through multiple pathways"/>

### Labeling systems
Labeling systems are consistent and clear naming conventions that help users find information. Labels should be intuitive and  convey information in the simplest format possible. There are three kinds of labeling systems: text-only, icon-only,  and combined.

#### Text-only labels

Text-only labels use clear and explicit words to describe the content or function without additional cues like icons. These labels help users understand exactly what they will find or what action will occur.
- Use text-only or combined labels for navigation menus. Use icon-only labels especially for navigation menus

<img src="https://design.visa.com/assets/content/ia/ia-content-do.svg" alt="A horizontal navigation bar with three tabs labeled Home, Inbox, and Calendar"/>

#### Icon-only labels

Icon-only labels use icons to represent the content or function helping users quickly navigate and understand content. Icons should be intuitive and quickly recognizable, helping users to quickly navigate and understand content. These are typically used on mobile experiences where combined or text-based labels might require too much space.
<br/>
**Note:** Icon-only labels should not be the main labeling strategy in your product experience. A text-only or combined label is preferred.
- Use icon-only labels especially for navigation menus. This can be used very sparingly on mobile, such as a hamburger menu.

<img src="https://design.visa.com/assets/content/ia/ia-content-dont.svg" alt="A top app bar with a menu icon button, search icon button, and a profile icon button"/>

#### Combined labels

Combined labels use both text and icons to provide more cues about the content or function. This method enhances meaning by combining text with visuals to help with quick recognition.
- Use text-only or combined labels, especially for navigation menus.
- Ensure icons clearly match the text displayed to enhance meaning and avoid confusion.

<img src="https://design.visa.com/assets/content/ia/ia-content-do-1.svg" alt="A horizontal navigation bar with three tabs labeled Home, Inbox, and Calendar with leading icons"/>

### Navigation systems
Navigation systems guide users through content, helping them find information and complete actions quickly. Effective navigation can enhance an experience by providing clear pathways to information, reducing frustration, and increasing efficiency. They play a crucial role in ensuring users can find what they need without disorientation and achieve their goals with minimal effort. VPDS provides designs for common navigation experiences to ensure users can find information quickly. For more information, visit [Anchor link menu](https://design.visa.com/components/anchor-link-menu/usage), [Breadcrumbs](https://design.visa.com/components/breadcrumbs/usage), [Horizontal navigation](https://design.visa.com/components/horizontal-navigation/usage), [Navigation drawer](https://design.visa.com/components/navigation-drawer/usage), [Tab bar](https://design.visa.com/components/tab-bar/usage), [Top app bar](https://design.visa.com/components/top-app-bar/usage), or [Vertical navigation](https://design.visa.com/components/vertical-navigation/usage).

### Search systems
Search systems are mechanisms enabling users to locate specific information quickly using search queries and filters. Effective search systems improve user satisfaction, reduce time spent finding information, and help users complete tasks more efficiently, especially in large or complex information structures.
- Always provide accurate and relevant results to help maintain user engagement and trust in the system.
- Implement flexible search criteria so users can find relevant results regardless of the format or spelling of their query.

## Steps to create effective information architecture

### Step 1: User research

Conduct interviews, surveys, and usability tests to gain insights into user needs, behaviors, and pain points. Analyze this data to inform information architecture (IA) decisions, ensuring the design aligns with user expectations and improves overall user experience.

### Step 2: Content inventory and audit

Examine your website or experience to identify existing content and help teams define all the items or objects in their system. This activity can help you explore and refine your IA with a more informed perspective.

### Step 3: Sitemap creation

Develop a detailed sitemap and wireframes to visually represent the site's structure, illustrating the hierarchy, navigation paths, and content relationships. This helps align your team as they build an experience to ensure clarity and usability.

<img src="https://design.visa.com/assets/content/ia/sitemap.svg" alt="A single-tier tree diagram showing a sitemap"/>

### Step 4: Wireframing and prototyping

Create visual blueprints of the layout and navigation for your experience. Wireframes provide a basic, low-fidelity representation of the design, focusing on structure and content placement without detailed styling. Prototypes build on wireframes with interactive elements and higher fidelity content, enabling designers and stakeholders to test and iterate on user interactions and design concepts before final development.
<br/>
The fidelity level (low, medium, or high) used depends on the development stage, with lower fidelity for early conceptual stages and higher fidelity for later, more detailed designs. Learn more about using medium fidelity content in [Placeholder text](https://design.visa.com/content/placeholder-text).

<img src="https://design.visa.com/assets/content/ia/wireframe.svg" alt="A diagram showing an active prototype where a user is navigted to various pages once they click certain buttons"/>

### Step 5: Usability testing

Continuously test the IA of your product experience to gather feedback and make improvements. This process includes planning, designing realistic tasks, conducting tests with representative users, analyzing results, and refining the IA based on findings. Integrating usability testing ensures a user-centered structure to improve overall usability and satisfaction.

## Progressive disclosure
Progressive disclosure is an IA principle that helps manage complexity by revealing information progressively to users. It starts with presenting a simple, uncluttered interface that shows only the most essential information and actions. As users interact with the system, additional information and options are revealed based on their needs and actions, ensuring users are only presented with relevant information.
<br/>
This approach prevents information overload.  Implementing progressive disclosure involves showing primary actions first, providing progressive details through links or buttons, and offering contextual help when needed, ultimately creating more intuitive and user-friendly interfaces.
<br/>
Benefits of progressive disclosure include improved usability, enhanced learning, and better decision-making, as users can focus on the task at hand without being distracted by unnecessary details. For example, an online banking application may initially show only the account balance and recent transactions, with options for transferring money or viewing detailed statements becoming available as users navigate. Learn more about progressive disclosure in [Forms](https://design.visa.com/patterns/forms).

<img src="https://design.visa.com/assets/content/ia/wireframe-1.svg" alt="A diagram showing an active prototype where a user is shown subsequent input fields upon entering some personal information"/>



---

# index

---
title: Messaging
description: Craft content for alert components to increase trust, reduce errors, and improve system performance.
meta_description: Craft content for alert components to increase trust, reduce errors, and improve system performance.
thumbnail: assets/content/alert-messaging-graphic.svg
---

Messages provide information about changes in a system or persistent conditions. Messaging applies to a range of components such as badges, banners, dialogs, flags, notification trays, section messages, and tooltips. Language used in these components is critical as they increase trust, reduce the likelihood of errors, and improve system performance.
<br/>
For specific guidance on how to decide on the right component for your context, where to place it, and its level of disruption, visit [Feedback and status](https://design.visa.com/patterns/feedback-and-status).  

## Anatomy

<img src="https://design.visa.com/assets/content/messaging/messaging-anatomy.svg" alt="A dialog with callout A indicating the optional title, callout B indicating the required message, and callout C indicating the required call to action."/>

**A. Title (optional):**  Descriptive text previewing the purpose of an alert.<br/>
**B. Message (required):** Text elaborating on the nature of the message or providing important context.<br/>
**C. Call to action (CTA) (required):** Buttons or links enabling users to respond to alerts by taking relevant actions.

## Best practices

- Always use sentence case except for proper nouns or acronyms.
- Use plain language and avoid abbreviations or jargon.
- Be brief, descriptive, and direct. 
- Keep the information useful. Don’t disrupt the user’s experience unless necessary. 

### Titles

- Limit titles to three to five descriptive words, using the description to provide additional details. 
- Avoid using unnecessary articles like “the” or “an”.  
- Don’t include punctuation. 
- Use descriptive language that indicates the purpose of the alert instead of terms like “warning” or “error”. 

### Messages

- Provide details on the reason for the alert without being technical.
- Use contextually relevant language to help users understand why the message is important. 
- Clearly outline the simplest way to fix the problem (if applicable) without sending them to another location for answers.

### Calls to action

- Give users the opportunity to edit, view, or in some cases undo their actions, especially if they’ve just created something or changed important settings. 
- Use clear, actionable language that is easy to understand without additional context or information.
- Avoid using unnecessary articles like “the” or “an”.  
- Don’t include punctuation. 
- Avoid ableist verbs that focus on senses. For example, use “Play video” instead of “Watch video”.
- Include a “dismiss”, “cancel”, or “close” button if the alert doesn’t include a close “x” in the top right corner. 
- Learn more about calls to action in [Grammar and punctuation](https://design.visa.com/content/grammar) or by visiting [Button](https://design.visa.com/components/button/usage).
<br/>
<br/>

## Voice and tone

Voice and tone are key elements to creating alert messages that are helpful without placing blame on the user. The guidance below discusses voice and tone recommendations specific to messages. To learn about voice and tone recommendations in other use cases, visit [Grammar and punctuation](https://design.visa.com/content/grammar).

### Active and passive voice

Using active or passive voice depends of the context and purpose of the message. As a general rule, active voice works better for providing clear, direct instructions, while passive voice is better for explaining errors or mistakes.
<br/>
Use the active voice whenever possible. If the message sounds harsh, adjust to the passive voice to soften the message.
<br/>
Learn more about [active and passive voice](https://design.visa.com/content/grammar/#active-and-passive-voice) in Grammar and punctuation.

#### Active voice examples

Use the active voice to communicate success, instructions, or neutral updates. This ensures it’s clear to the user what actions they must take or when they’ve completed a task successfully. 

Example usage of active voice

- Use: You have successfully logged in.
- Instead of: The login has been successfully completed.

- Use: Your account is now active.
- Instead of: Account has been activated successfully.

- Use: You have 3 unread messages.
- Instead of: 3 messages have been unread.

- Use: You can update your privacy preferences in Settings.
- Instead of: Privacy preferences can be updated in Settings.

#### Passive voice examples

Use the passive voice to communicate errors and warnings. This helps avoid placing blame on users and softens negative updates. It’s also helpful when the cause of an error is unclear or nobody is at fault, such as network connection issues.  

Example usage of passive voice

- Use: Page not found.
- Instead of: We can’t find this page.

- Use: Incorrect credentials. Please try again.
- Instead of: You entered the credentials incorrectly.

- Use: Network connection error. Please try again.
- Instead of: We lost connection. Please try again.

- Use: All required fields must be completed.
- Instead of: You must complete the required fields.

### Tone

At Visa, our tone is flexible depending on the context. When writing alert messages, prioritize giving clear, efficient information to help users complete their goals quickly. The tone should be neutral, clear, and helpful. 
- Inform the user without causing alarm. Provide clear, concise instructions that help complete tasks.
- Be direct when providing next steps or instructions for correcting errors. 
- Avoid using technical jargon, codes, acronyms, and terminology that assume the user has advanced knowledge.
- Avoid overly playful language, tongue-in-cheek references, or plays on words that aren’t widely understood. 
- Avoid accusing or patronizing the user for failing to follow directions or misusing the system.

## Examples

### Informational message
Informational messages should provide information without disrupting the user’s workflow. They can communicate a change in state or important information about an experience or feature.

#### Banner

<img src="https://design.visa.com/assets/content/messaging/info-messaging-banner.svg" alt="Informational banner titled New feature available You can now download your transaction history for the last 3 years. A button reads Download transaction history"/>

#### Dialog

<img src="https://design.visa.com/assets/content/messaging/info-messaging-dialog.svg" alt="Informational dialog titled Update available A new version of the app is available. Update for security and performance improvements. 2 buttons read Update and Close"/>

#### Flag

<img src="https://design.visa.com/assets/content/messaging/info-messaging-flag.svg" alt="Informational flag titled Your subscription automatically renews on June 1."/>

#### Section message

<img src="https://design.visa.com/assets/content/messaging/info-messaging-section-message.svg" alt="Informational section message titled Transactions may be delayed Please note that transactions may take up to 24 hours to reflect in your account balance."/>

### Success messages

Success messages are used to confirm a user’s action or task completion. They usually don’t require additional actions unless providing a pathway to undo the action being confirmed. 

#### Banner

<img src="https://design.visa.com/assets/content/messaging/success-messaging-banner.svg" alt="Success banner titled Sharing settings updated Collaborators now have editing privileges. You can change privileges in your settings at any time."/>

#### Dialog

<img src="https://design.visa.com/assets/content/messaging/success-messaging-dialog.svg" alt="Success dialog titled Update available A new version of the app is now available. Update now for enhanced security and bug fixes. 2 buttons read Update and Close"/>

#### Flag

<img src="https://design.visa.com/assets/content/messaging/success-messaging-flag.svg" alt="Success flag titled Updates successfully installed. Close this window and restart the app."/>

#### Section message

<img src="https://design.visa.com/assets/content/messaging/success-messaging-section-message.svg" alt="Success section message titled Transaction complete Your payment was successful. A button reads Access summary"/>

### Warning messages

Warning messages are used to indicate a potential change in the user’s workflow or access to the system. Warning messages should use clear, informative language that conveys the appropriate level of urgency so the user knows how to respond.

#### Banner

<img src="https://design.visa.com/assets/content/messaging/warning-messaging-banner.svg" alt="Warning banner titled Scheduled maintenance in progress The system is currently undergoing routine maintenance which may affect some of our services."/>

#### Dialog

<img src="https://design.visa.com/assets/content/messaging/warning-messaging-dialog.svg" alt="Warning dialog titled Reset settings Are you sure you want to restore the default settings? All custom settings will be lost. 2 buttons read Reset settings and Cancel"/>

#### Flag

<img src="https://design.visa.com/assets/content/messaging/warning-messaging-flag.svg" alt="Warning flag titled Backup in progress. Don’t refresh the page."/>

#### Section message

<img src="https://design.visa.com/assets/content/messaging/warning-messaging-section-message.svg" alt="Warning section message titled Edits available Changes have been made since you last opened this document. Refresh to access changes. A button reads Refresh page"/>

### Error messages

Error messages are used to indicate a a problem has already occurred or that there’s been a mistake during the user’s workflow. They should draw attention to what has happened, communicate the consequences, and tell the user what to do to move forward.
<br/>
Error messages should use clear, informative language that conveys the appropriate level of urgency so the user knows how to respond.

#### Banner

<img src="https://design.visa.com/assets/content/messaging/error-messaging-banner.svg" alt="Error banner titled Dashboard unavailable Dashboard failed to load. Wait a few minutes and try again."/>

#### Dialog

<img src="https://design.visa.com/assets/content/messaging/error-messaging-dialog.svg" alt="Error dialog titled Payment error Payment not processed. Check your payment details and try again. 2 buttons read Update payment and Cancel"/>

#### Flag

<img src="https://design.visa.com/assets/content/messaging/error-messaging-flag.svg" alt="Error flag titled Your response exceeds the maximum limit of 200 characters."/>

#### Section message

<img src="https://design.visa.com/assets/content/messaging/error-messaging-section-message.svg" alt="Error section message titled Required fields incomplete Please complete all required fields before proceeding. A button reads Refresh page"/>

#### Inline error messages

Inline error messages are common across a range of components. For help prototyping content for common error messages, VPDS offers component variants with pre-written messages. Access these in the assets panel of our [Design kits](https://design.visa.com/designing/design-kits).

### Badges

Badges are compact components used to communicate status with limited text. There are generally two categories of badges. The first is numeric badges, which display a count or tally of notifications. The second is informational badges, which provide status updates when the number of notifications is unknown or irrelevant. 
<br/>
To learn more, visit [Badge guidance](https://design.visa.com/components/badge/usage).

  When to use and when not to use different types of badges

- Do: Use single-word labels like ”Authorized”, “Pending”, “Paid”, “Unpaid”, “Shipped”, “Overdue”, “Ready”, “Complete”, or “Canceled”.
- Don't: Use verbs like “Cancel” as this can lead users to think the badge is a call to action.

- Do: Use no more than two to three short words to describe more complex information like “Out of stock”, “In stock”, or “On backorder”.
- Don't: Use vague labels that don’t appropriately match the urgency of the status status such as, “information,” where more context is needed.

- Do: Use numeric formatting for number badges, like “1”, “12”, “30”, etc.
- Don't: Write out numbers in text, as this can take up too much space.



---

# index

---
title: Placeholder text
description: Replace lorem ipsum text with relevant examples or custom placeholder content.
meta_description: Explore how and when to replace lorem ipsum text with relevant examples or custom placeholder content.
thumbnail: assets/content/placeholder-text-graphic.svg
---

This section outlines guidance for using mid-fidelity content as placeholder text in user-facing contexts. This generally means replacing lorem ipsum text with descriptive text to provide additional context and meaning within prototypes. 

## Medium fidelity content

Medium fidelity content, also known as mid-fidelity content, refers to text and labels that describe an element or use case. This is different from low-fidelity content, like lorem ipsum text, or high-fidelity content you’d find in a functional interface.
- Use medium fidelity content when planning and prototyping, as it helps communicate the purpose of an element without requiring substantial content support.

### Naming formula

To ensure mid-fidelity labels are clear and descriptive, VPDS recommends using the **descriptor + text category** formula. This formula results in labels that are clear and descriptive by combining contextual information (descriptors) with text that identifies the purpose of the label (text categories).
<br />
**Note:** Descriptors can be left out of labels if the text category provides sufficient context. However, the text category should always be included. 

#### Descriptors

Descriptors specify the exact element being labeled with context like location, category, or type. They help indicate sequential order, hierarchy, grouping, or placement. Here are the most common ones used throughout VPDS:

- Component names (like button, checkbox, or link)
- Group
- Level (like L1, L2, L3)
- Page
- Primary, secondary, tertiary
- Section
- Variant names (like informational, success, warning, or error) 
<br />
**Note:** Use simple descriptors whenever possible, avoiding terms like 1st, 2nd, 3rd, first, second, third, or primary, secondary, or tertiary, as they become complicated beyond the third position. An exception to this rule is calls to action, where labeling “Primary action” and “Secondary action” are common. 

#### Text categories

Text categories indicate the type of content being used in an element. These are an essential piece of mid-fidelity labels and should always be included. Here are the most common ones used throughout VPDS:

- Action (for buttons)
- Body text
- Header (for tables)
- Heading
- Label
- Subtitle
- Subheading
- Title

#### Examples

Below are examples of this naming convention formula used in context. For the specific naming conventions of each component, refer to their respective anatomy diagrams at the top of each page.

<img src="https://design.visa.com/assets/content/placeholder-text/placeholder-naming-ex-1.svg" alt="Checkbox group with a label"/>
In this example, “group label” isn’t just any label, but one that describes the whole group of elements.

<img src="https://design.visa.com/assets/content/placeholder-text/placeholder-naming-ex-2.svg" alt="Anchor link menu with a section title"/>
In this example, “Section title” differentiates the anchor links in one section of the page from the title of the entire page.

## Inline messages

In components, descriptive text is known as an inline message and typically appears below the main text category like a title or label. Inline messages can be optional or required depending on the context or state of a component.<br />
- When composing generic inline messages, follow this formula: “This is required/optional text that describes the **component name / text category** in more detail.”
<br />
Having both the component name and text category isn’t always required. In some situations, it helps to refer to the component name if it looks similar to other components when taken out of context. In other instances, such as with more easily recognizable components, referring to just the text category is easier and simpler.

<img src="https://design.visa.com/assets/content/placeholder-text/placeholder-inline-1.svg" alt="Checkbox with the word checkbox crossed out of the label and within the description"/>
Constantly referring to the checkbox component within each element can get repetitive when users know which component they’re looking at.

<img src="https://design.visa.com/assets/content/placeholder-text/placeholder-inline-2.svg" alt="Banner with the word banner in placeholder description"/>
As titles are turned off for banners by default, and banners may be confused with flags or section messages, it’s helpful for the message to refer specifically to the component name.

### Empty states

Inline messages should also be included in the empty state of a component to inform users when there’s no data to display in their current view. This can happen if searching or filtering yields no results, data hasn’t been added to an element, or the user doesn’t have permission to view the data. Reference [Feedback and status](https://design.visa.com/patterns/feedback-and-status) for more information.

## Custom content 

Custom or fictitious content can be added to prototypes to help further indicate contextualize elements or add examples. Use this level of specificity when trademarked brands can’t be used but a real or simulated use case is needed to provide deeper context than generic labels. Refer to [Fictitious brands](https://bookmarks.visa.com/vpds-fictitious-brands)<!-- aria-label="Fictitious brands (internal only, opens in a new tab)" --> for more guidance.

<img src="https://design.visa.com/assets/content/placeholder-text/placeholder-custom.svg" alt="Mobile mockup with a content card with custom high fidelity content"/>



---

# index

---
title: Readability
description: Make your content easy to read and understand so people can quickly find what they're looking for.
meta_description: Learn how to make your content easy to read and understand, so people can quickly find what they're looking for.
thumbnail: assets/content/readability-graphic.svg
header_image: assets/content/readability-overview.svg
---

Readability is a measure of how easy it is to read text-based content, which is critical for designing efficient and effective experiences. Users don’t spend a lot of time absorbing information, so it’s important to design experiences that promote scanability with high reading comprehension. This section provides guidance on maintaining clear, readable content.
<br/>
Ensuring readability requires a combination careful language and phrasing, and visual design. While this section primarily focuses on language, reference [Typography](https://design.visa.com/base-elements/typography/usage) to learn more about, access, and download Visa typefaces to help support readability.

## Reading level

Reading level is one method for measuring readability. Certain formulas, like the the Flesch Reading Ease Score (FRES) and the Flesch-Kincaid Grade Level Test, can help with this. For high readability, Visa uses a 6th grade reading level for all product and documentation content at a global scale.

### Simple language

Many words have synonyms with a different reading level. Always choose shorter, simpler words to increase reading speed and decrease reading level.

Examples of simple language

- Use: About
- Instead of: Approximately

- Use: Buy
- Instead of: Purchase

- Use: Go
- Instead of: Proceed

- Use: Help
- Instead of: Assist

### Sentence length

Shorter sentences promote readability. Use shorter and simpler words, phrases, sentences, and sentence structures to express clearer thoughts. Long, complex sentences keep users from being able to understand information quickly.
<br />
Use this chart when writing to help you boost readability:

Difficulty levels of reading sentence by number of words per sentence

- Number of words per sentence: Very easy to read

- Number of words per sentence: Easy

- Number of words per sentence: Fairly easy

- Number of words per sentence: Standard

- Number of words per sentence: Fairly difficult

- Number of words per sentence: Difficult

- Number of words per sentence: Very difficult

## Hierarchy and spacing

Effective hierarchy makes content easy to consume and understand. It helps with scanability and tells users what information to focus on first. Think of it as your tool in guiding the reader’s attention to the content you want in the order you want them to see it.
- Ensure headings are descriptive to support scanning. 
- Keep the appearance of text in the same category consistent. For more information, reference [Typography](https://design.visa.com/base-elements/typography/usage).
- Always use sentence case except for proper nouns or acronyms. For more information, reference [Grammar and punctuation](https://design.visa.com/content/grammar).
- Use sufficient negative space to prevent information overload. 



---

# index

---
title: Voice and tone
description: Ensure products sound and feel like Visa by learning the foundational pillars of our voice and tone.
meta_description: Ensure products sound and feel like Visa by learning the foundational pillars of our voice and tone.
thumbnail: assets/content/voice-and-tone-graphic.svg
---

Voice and tone are key elements that establish how products sound and feel. Voice refers to Visa’s personality and values, which should appear consistently across experiences, while tone is an expression of mood and changes depending on context. This section describes the pillars of Visa’s voice and provides context on when and how to emulate different tones.

## Voice
To create cohesive, consistent product experiences, we should intentionally craft our content to maintain a voice that feels distinct to Visa. Writing without this voice in mind can create disjointed experiences that leave the user feeling confused and could highlight that content is being authored by multiple people with different approaches.

<br/ >
Our voice is embodied by 3 core qualities: active, readable, and human. The following sections unpack these qualities and explain how to use them to ensure our product content remains consistent.<br/><br/>

<FeatureWithIcon icon={VisaGlobalHigh}>
  <Typography variant="overline" tag="h3">Active</Typography>
  <Typography variant="subtitle-3" tag="strong" style={{marginBottom: '0px'}}>Actionable and global</Typography>
  <Typography variant="body-2">Visa connects the world through fast, secure financial access enabled by a partner-trusted network. Our content should support and help users complete tasks quickly and efficiently. Ensure everyone, everywhere can meet their goals using clear, actionable language that translates seamlessly across the globe.</Typography>
</FeatureWithIcon>

<FeatureWithIcon icon={VisaGlossaryHigh}>
  <Typography variant="overline" tag="h3">Readable</Typography>
  <Typography variant="subtitle-3" tag="strong" style={{marginBottom: '0px'}}>Clear, concise, thoughtful</Typography>
  <Typography variant="body-2">Make experiences effortless by putting users first. Author content that anticipates what the user needs and answers their questions before they’ve asked—like a trusted advisor. Use direct and consistent language that’s easy to scan, makes task completion easy, and simplifies complex concepts.</Typography>
</FeatureWithIcon>

<FeatureWithIcon icon={VisaLikeHigh}>
  <Typography variant="overline" tag="h3">Human</Typography>
  <Typography variant="subtitle-3" tag="strong" style={{marginBottom: '0px'}}>Energetic, authentic, personable</Typography>
  <Typography variant="body-2">Our products are designed by real people for real people behind the screen. Use inclusive language to empathize with users and show consideration and recognition of their humanity. Be personable and conversational—not too formal, not too casual, and never robotic.</Typography>
</FeatureWithIcon>

## Tone
Tone is a device used by an author to elicit a feeling, making our messaging more relevant and useful to users as they complete their tasks and goals. This ensures we deliver the most useful language, exactly when users need it, and in the most effective way possible to reinforce the relationship between users and our products.

<br />
In general, we recommend a neutral tone that’s straightforward and direct. In certain contexts, tone can be adjusted to convey feelings like encouragement, enthusiasm, or positivity. 

### Tones to use

Types of tones to use

- Tone: Positive, congratulatory
- Feeling conveyed to users: Success, task completion
- Context: Success! Your account has been created.

- Tone: Engaging, helpful
- Feeling conveyed to users: Instructions, support, documentation
- Context: Need help? Our support team is just a click away.

- Tone: Clear, direct
- Feeling conveyed to users: Error, alert
- Context: Something went wrong while processing your transaction. Try again in a few moments.

- Tone: Inviting, enthusiastic
- Feeling conveyed to users: First-time use, onboarding, support
- Context: Welcome to your dashboard! Ready to get started?

### Tones to avoid

Types of tones to avoid

- Tone: Aggressive, insensitive, dismissive

- Tone: Complicated, elaborate, intimidating

- Tone: Condescending, superior, pretentious

- Tone: Apathetic, indifferent, lifeless

- Tone: Ambiguous, confusing, indirect



---

# code

---
title: Start contributing to VPDS
description: Learn more about contributions and how you can help shape the future of the Visa Product Design System.
meta_description: Learn more about contributions and how you can help shape the future of the Visa Product Design System.
side_nav_title: Code
side_nav_order: 2
---

## Prep: Identify and validate the work
Before proposing a new component, pattern, or enhancement, make sure your code contribution is necessary. Start by exploring existing resources and checking the VPDS backlog. 
1. **Explore existing resources:** Browse [components](https://design.visa.com/components) and [patterns](https://design.visa.com/patterns) to avoid duplication.
2. **Check the VPDS backlog:** Search for open items labeled “contribution” or “in progress” in the [VPDS backlog (internal only)](https://bookmarks.visa.com/vpds-backlog).
3. **Assess design support:** Determine if you need design support, especially if you’re introducing a new visual pattern (not just fixing a code bug).

<br />
**Note:** At this time, the VPDS team only has an outlined process for internal code contributions from Visa employees. External contributors may create new issues to work on, but don't have access to our Jira backlog.

### Questions to ask
- Does your contribution solve a common problem?
- Is it flexible enough to serve multiple use cases?
- Will it help other design system users?
- Does it replicate anything in the system? If so, is there evidence that your solution is more effective?
- Is it an enhancement of an existing area of the system, or something new? 
- Does it align with Visa’s accessibility and brand standards?
- What impact could your solution have on existing implementations?
- Do you have the necessary resources—such as people, time, and tools—to ensure the contribution meets VPDS standards?<br/><br/>

<div className="v-mt-24 v-flex v-flex-col v-gap-12">
    Not sure what kind of contribution you have or where to start? Take our quiz.
    <ContributingQuizModal client:only="react" />
</div>

## Intake: Propose your idea
Once you’ve confirmed there’s a gap or opportunity, formally propose your idea. Contributors should submit a detailed proposal and the VPDS team will provide feedback and schedule follow-ups if needed.<br/>
1. **Determine your type of submission**<br/>
    a. **For bug fixes:** Assign the ticket to yourself after reviewing the [VPDS backlog (internal only)](https://bookmarks.visa.com/vpds-backlog).<br/>
    b. **For enhancements or new contributions:** Complete the [VPDS contribution intake form (internal only)](https://bookmarks.visa.com/vpds-contribution-intake-form) and include all required documentation.<br/>
2. **Define acceptance criteria:** Clearly outline what success looks like for your issue using our [acceptance criteria template (internal only)](https://bookmarks.visa.com/vpds-acceptance-criteria).
3. **Initial review:** The VPDS team will review your submission, provide feedback, and schedule follow-ups if needed.
4. **Present to the contribution guild (for new contributions):** If your proposal moves forward, you’ll be invited to present it to the VPDS guild. This meeting provides the opportunity to explain your idea, answer questions, and gather additional feedback.
5. **Guild decision (for new contributions):** After your presentation, the guild will review and vote on your proposal, considering priorities, business needs, and feasibility. You’ll be notified once a decision is made.

## Plan: Align and scope
If your idea is approved, you’ll move into the planning phase. Here, you and the VPDS team will work with you to define the scope and clarify roles.
1. **Form a working group:** Collaborate with the VPDS team—including design, content, development, and accessibility experts—to align on roles and responsibilities.
2. **Define the scope:** Decide together what’s in and out of scope, establish required deliverables, and set timelines.
3. **Clarify support pathways:** Set up check-ins with your VPDS working group or attend [office hours (internal only)](https://bookmarks.visa.com/vpds-office-hours)<!-- aria-label="Join our office hours (internal only, opens in a new tab)" --> for additional support.

## Set up: Configure your environment
Follow the guidelines for the libraries you’ll be working in to ensure your coding environment is correctly configured.
- [HTML/CSS](https://github.com/visa/nova-styles/blob/main/CONTRIBUTING.md)<!-- aria-label="HTLM/CSS opens in new tab)" --> 
- [Angular](https://github.com/visa/nova-angular/blob/main/CONTRIBUTING.md)<!-- aria-label="Angular opens in new tab)" --> 
- [React](https://github.com/visa/nova-react/blob/main/CONTRIBUTING.md)<!-- aria-label="React opens in new tab)" --> 
- [Flutter](https://github.com/visa/nova-flutter/blob/main/CONTRIBUTING.md)<!-- aria-label="Flutter opens in new tab)" -->
<br/>
When developing your code, remember to:
- Build using the latest version of Nova and your preferred code library.
- Use and adhere to Visa's secure coding tools, guidelines, and practices.
- Avoid unnecessary dependencies in your code.

## Build: Create and refine
1. **Develop the code:** Write code to address the issue according to the agreed acceptance criteria.
2. **Run automated tests:** Verify that all components pass aXe automated accessibility tests. These tests are included in the code libraries.
3. **Ensure code coverage:** Maintain at least 80% code coverage through testing. Add new tests as needed for your contribution.
4. **Add documentation:** Document any new classes or properties, and include examples where applicable.
5. **Format your code:** Use [Prettier](https://github.com/prettier/prettier)<!-- aria-label="Prettier opens in new tab)" --> to maintain consistency and readability. Each web library has its own .prettierrc file at the root, and Prettier is automatically installed as a development dependency.
6. **Write standard commit messages:** Follow the [standard-commit guidelines](https://www.conventionalcommits.org/en/v1.0.0/)<!-- aria-label="Standard commit guidelines open in new tab)" --> to format your commit messages clearly and consistently. 

## Submit: Create a pull request
1. **Link the issue:** Reference the original issue in your pull request description to close the issue upon merging.
2. **Review and feedback:** Gather any final feedback and make necessary updates. **Note:** Not all submissions will be accepted.  If not accepted, constructive feedback will be provided.
3. **Go live:** After submission, your contribution will undergo rigorous accessibility and QA testing by the VPDS team before it’s published. This process may take some time.

## Want to contribute design assets or report a design issue?
Learn how you can contribute design assets or report issues. 
<br/>

<div className="v-flex v-gap-12 v-flex-wrap">
<a href={`https://design.visa.com/contributing/design`} class="v-button v-button-secondary">Contribute designs</a>
</div>

---

# design

---
title: Start contributing to VPDS
description: Learn more about contributions and how you can help shape the future of the Visa Product Design System.
meta_description: Learn more about contributions and how you can help shape the future of the Visa Product Design System.
side_nav_title: Design
side_nav_order: 1
---

## Prep: Make sure it's needed
Before proposing a new component, pattern, or enhancement, make sure your contribution is necessary.  Start by exploring existing resources and checking the VPDS backlog. 
- **Explore existing resources:** Browse [components](https://design.visa.com/components) and [patterns](https://design.visa.com/patterns) to avoid duplication.
- **Check the VPDS backlog:** Search for open items labeled “contribution” or “in progress” in the [VPDS backlog (internal only)](https://bookmarks.visa.com/vpds-backlog).<br/><br/>

**Note:** At this time the VPDS team is only accepting internal design contributions from Visa employees. 

### Questions to ask
- Does your contribution solve a common problem?
- Is it flexible enough to serve multiple use cases?
- Will it help other design system users?
- Does it replicate anything in the system? If so, is there evidence that your solution is more effective?
- Is it an enhancement of an existing area of the system, or something new? 
- Does it align with Visa’s accessibility and brand standards?
- What impact could your solution have on existing implementations?
- Do you have the necessary resources—such as people, time, and tools—to ensure the contribution meets VPDS standards?<br/><br/>

<div className="v-mt-24 v-flex v-flex-col v-gap-12">
  Not sure what kind of contribution you have or where to start? Take our quiz.
  <ContributingQuizModal client:only="react" />
</div>

## Intake: Propose your idea
Once you’ve confirmed there’s a gap or opportunity, formally propose your idea. The VPDS team will review your submission, provide feedback, and schedule follow-ups if needed.
1. **Submit an intake form:** Complete the [VPDS contribution intake form (internal only)](https://bookmarks.visa.com/vpds-contribution-intake-form) and include all required documentation.
2. **Initial review:** The VPDS team will review your submission, provide feedback, and schedule follow-ups if needed.
3. **Present to the contribution guild:** If your proposal moves forward, you’ll be invited to present it to the VPDS guild. This meeting provides the opportunity to explain your idea, answer questions, and gather additional feedback.
4. **Guild decision:** After your presentation, the contribution guild will review and vote on your proposal, considering backlog priorities, business needs, and feasibility. You’ll be notified once a decision is made.

## Plan: Align and scope
If your idea is approved, you’ll move into the planning phase. Here, you and the VPDS team will work with you to define the scope and clarify roles.
1. **Form a working group:** Collaborate with the VPDS team—including design, content, development, and accessibility experts—to align on roles and responsibilities.
2. **Define the scope:** Decide together what’s in and out of scope, establish required deliverables, and set timelines.
3. **Clarify support pathways:** Set up check-ins with your VPDS working group or attend [office hours (internal only)](https://bookmarks.visa.com/vpds-office-hours)<!-- aria-label="Join our office hours (internal only, opens in a new tab)" --> for additional support.

## Define: Discovery and research
In this phase, gather additional information or use existing research to outline what’s needed, why it’s needed, and how it might be used across different contexts.
1. **Conduct or gather existing research:** Interview stakeholders to identify pain points and understand constraints (such as accessibility, responsiveness, interactivity, and localization). Research industry trends and best practices from organizations like the [Nielsen Norman Group](https://www.nngroup.com/). 
2. **Competitive analysis:** Review how other teams at Visa or other design systems have addressed similar needs. Collect screenshots, prototypes, or code, and document relevant solutions.
3. **Create a design brief:** Clearly document the design needs using the [Contribution template (internal only)](https://bookmarks.visa.com/vpds-contribution-template) in Figma.

## Design: Create and refine
Contributors are responsible for creating and refining the design based on the design brief, while the VPDS team provides feedback throughout.
1. **Sketch and draft:** Sketch your idea or refine existing designs. Begin drafting initial guidelines—such as when to use or not use the component, best practices, and more—using the [Usage guidelines template (internal only)](https://bookmarks.visa.com/vpds-usage-guidelines-template). 
2. **Prototype and outline specs:** Refer to the Nova Figma library to turn your sketches into prototypes. Document states, redlines, platform scaling, and details using the [VPDS specs checklist (internal only)](https://bookmarks.visa.com/vpds-specs-checklist).
3. **Refine and review:** Continue refining your design and documentation, ensuring all states, redlines, and scaling considerations are captured. Keep deliverables up to date and respond to VPDS feedback as needed.

## Deliver: Approval and handoff
Contributors are responsible for finalizing and delivering all required designs and documentation. The VPDS team will review and provide any final feedback before approval.

1. **Present to the VPDS team:** Walk the team through your designs and documentation, highlighting key decisions and addressing questions.
2. **Apply final feedback:** Gather any final feedback and make necessary updates.
3. **Submit final designs and documentation:** Package and deliver the final designs and usage guidance to the VPDS team for approval and inclusion in the system.

## Want to contribute code or report a bug?
Learn how you can contribute code or report issues. 
<br/>

<div className="v-flex v-gap-12 v-flex-wrap">
<a href={`https://design.visa.com/contributing/code`} class="v-button v-button-secondary">Contribute code</a>
</div>

---

# index

---
title: Start contributing to VPDS
description: Learn more about contributions and how you can help shape the future of the Visa Product Design System.
meta_description: Learn more about contributions and how you can help shape the future of the Visa Product Design System.
side_nav_title: Get started
tab_title: Overview
side_nav_order: 0
show_table_of_contents: false
---

The Visa Product Design System (VPDS) is built for our community. We invite designers, developers, and teams across Visa to contribute ideas, solutions, and improvements. Whether you’re enhancing a component, proposing a new pattern, or refining guidance—we welcome your input.

<div className="v-mt-48 v-flex v-flex-col v-gap-12">
Want a quick overview of our contribution process? Take our quiz.

**Note:** While this quiz is publicly available, the VPDS team is only accepting internal design contributions from Visa employees. 

<ContributingQuizModal client:only="react" />
</div>

## Why contribute?

Contributing to VPDS helps scale accessible, inclusive, and consistent product experiences across Visa. By contributing, you:

- **Solve once, share widely:** Reusable solutions help other teams and reduce redundant work.
- **Promote best practices:** Contributions ensure consistent accessibility, usability, and brand standards.
- **Showcase your work:** Gain recognition from your peers and further the impact of your day-to-day work.
- **Foster a stronger design community:** Sharing knowledge between teams promotes a healthy design culture.
- **Build a system that reflects real needs:** Contributions based on real product challenges make the system future-proof.
- **Shape the tools you use every day:** Your feedback guides the system’s roadmap, priorities, and growth.

## Who can contribute?

Anyone at Visa can contribute to VPDS. Whether you’re a product designer, content designer, engineer, accessibility specialist, or researcher—your perspective is valuable. We especially encourage contributions from teams addressing real-world needs or edge cases not yet covered by the system.

## What can you contribute?

There are several types of contributions you can make.

### New components and patterns
A new contribution proposes a brand new component, pattern, or guidance to be added to the design system. This can be a design, content, or code contribution. Examples include creating a slider component or developing a bucket-picker pattern.
### Component and pattern enhancements
An enhancement contribution adds a new feature or interaction to existing components, patterns, or guidance. This can be a design, content, or code contribution. Examples include adding a processing state for text buttons or adding new interactions like hot keys.
### Code bug fixes
A bug fix is a code contribution that resolves issues in our coded components or patterns to ensure their behavior matches expectations. This can be a code contribution only. Examples include fixing accessibility issues, correcting visual discrepancies, or restoring broken interactions.

## How do contributions help?

Contributions help VPDS evolve to meet the needs of real products. Your participation helps:

- **Increase adoption** by making the system more comprehensive.
- **Improve quality** through shared knowledge and testing.
- **Make it easier for teams** to build the right thing, the right way, faster.
<br/>
The more we collaborate, the more powerful the system becomes.

## What's the contribution process?

Contributing to VPDS is a structured but flexible process:

- **Prep:** Review the [VPDS backlog (internal only)](https://bookmarks.visa.com/vpds-backlog) and existing [components](https://design.visa.com/components) or [patterns](https://design.visa.com/patterns) to ensure your idea is unique or an enhancement.
- **Intake:** Complete the [VPDS contribution intake form (internal only)](https://bookmarks.visa.com/vpds-contribution-intake-form) and present your idea to the VPDS Contribution Guild—a group that reviews and recommends contributions.
- **Plan:** If recommended, your contribution is added to the VPDS backlog and assigned a working group with design, content, development, and accessibility representatives.
- **Define:** Conduct any necessary discovery and research, using internal or external resources.
- **Design:** Bring well-developed ideas. The VPDS team is available for support during [office hours (internal only)](https://bookmarks.visa.com/vpds-office-hours)<!-- aria-label="Join our office hours (internal only, opens in a new tab)" --> before you submit for final approval.
- **Deliver:** Once approved, the VPDS team will publish design assets and work with engineering to add development assets to applicable libraries. Changes will be published to the VPDS website, along with quality assessments and communications about your contribution.

## Ready to contribute?

Help transform the Visa Product Design System with your contribution. 

<div className="v-flex v-gap-12 v-flex-wrap v-mt-12">
  <a
    href={`https://design.visa.com/contributing/design`}
    class="v-button v-button-secondary"
  >
    Contribute designs
  </a>
  <a href={`https://design.visa.com/contributing/code`} class="v-button v-button-secondary">
    Contribute code
  </a>
</div>


---

# accessibility

---
title: Bar chart
description: Chart that uses rectangular bars to represent and compare values across different categories or groups.
meta_description: Find accessibility guidelines for bar charts to represent and compare values across different categories or groups.
tab_title: Accessibility
tab_order: 1
---

This chart component has built-in accessibility features to support creating accessible charts from the start. These include descriptive tag properties, keyboard navigation controls, and tools to ensure sufficient color contrast. Find accessibility guidance below.

## Best practices 

Ensure the following best practices are met when implementing this component to create accessible data experiences for everyone, everywhere.

### Make thoughtful color choices

Ensure users of all abilities can understand the meaning of colors in your data visualization. Choose color combinations that provide sufficient contrast and add textures to support color-blind and low vision users.
#### Use accessible color palettes
Our data visualization color palettes are designed to ensure that data distinctions remain clear for users with various types of color vision deficiencies. Use this functionality to ensure sufficient contrast between colors and avoid relying only on color to differentiate categories or values. <br/><br/>For example, the Visa red to green divergent color palette ensures that all shades are seen as different values, even under different color-blindness simulators. Meanwhile, a default red to green color palette doesn’t make the shades distinct enough across the full range of the palette.

#### Add contrast with textures
Textures help differentiate categories when color doesn’t provide enough contrast. Use the texture fill option in our bar charts to improve accessibility for users with color vision deficiencies and maintain clarity when charts are printed in grayscale.

#### Outline light objects
Our chart components automatically add darker outlines to light-colored chart elements to ensure contrast and visibility against backgrounds and adjacent marks. Overriding this default behavior can make elements harder to distinguish from the chart background and reduce readability.

### Write clear alternative text

Use the chart components’ descriptive tag properties to provide concise and informative alternative text for screen readers. 

A table that provides guidance for writing chart accessibility properties.

- Accessibility property: Summarize what the chart shows and the type of data.<br/><br/>
Use simple language for straightforward charts. Describe the layout for uncommon chart types.<br/><br/>
Avoid repeating the chart title or subtitle.
- Guidance: “This bar chart shows monthly payment volume for this year compared to last year.”<br/><br/>
“This strip chart displays transaction volume across major European cities, with each city represented by a circle placed according to spending volume.”

- Accessibility property: Clearly state the takeaway and highlight key statistical insights and trends.<br/><br/>
Group data points to show patterns or outliers.<br/><br/>
Do not list numbers without explaining their meaning.
- Guidance: “Sales numbers increased every month except June and July.”<br/><br/>
“Europe and Asia Pacific had over 5% growth, while Asia Pacific lagged the global average at 1%.”

- Accessibility property: Explain which controls or filters affect the chart.<br/><br/>
Communicate any selections that have been applied to exclude or change the displayed data.
- Guidance: “The values in this chart are based on the filter selections applied to the dashboard.”

<br/>

### Add descriptive labels for data

Use the chart components’ custom labeling options to provide clear and descriptive names for displayed data. Labels like “num_transactions” may work during analysis, but “Number of transactions” is easier for users to understand and interpret.
#### Data labels
Data labels are the textual representations of data values in charts or tables. Use descriptive labels when presenting data to end users to provide clarity and avoid technical jargon or shorthand that may confuse non-technical audiences.
#### Tooltips
Tooltips add contextual information about data points when users hover or focus on chart elements. Clear and descriptive labels in tooltips help users understand the meaning of the data without requiring knowledge of internal naming conventions.

## Keyboard controls

Keyboard actions and their corresponding behaviors for bar charts

- Key: Enter the chart area/drill down a level on the chart area or a bar group.

- Key: Drill up a level on a bar group or a bar.

- Key: Move among sibling bar groups or bars when focusing on a bar group or a bar.

- Key: Press and hold when using the arrow keys for the best navigation experience on a Mac (VoiceOver).

- Key: Dismiss the tooltip at any time.

<br/>



---

# code

---
title: Bar chart
description: Chart that uses rectangular bars to represent and compare values across different categories or groups.
meta_description: Get code for bar charts to represent and compare values across different categories or groups.
tab_title: Code
tab_order: 3
show_table_of_contents: true
---

<ChartsCodeExampleList
	client:only="react"
	chartExampleId="bar-chart-simple-trend"
	chartTag="bar-chart"
/>

<br></br><br></br>

---

# examples

---
title: Bar chart
description: Chart that uses rectangular bars to represent and compare values across different categories or groups.
meta_description: Explore examples for bar charts to represent and compare values across different categories or groups.
tab_title: Examples
tab_order: 2
---

Explore our bar chart examples to see how the VCC bar chart component can be customized for specific business scenarios and analysis tasks.
<br/>
Find design assets for these bar chart examples in our Figma [Data Experience Charts (internal only)](https://bookmarks.visa.com/vpds-data-experience-charts) library.

<BarChartSimpleTrend />
<BarChartTrend />
<BarCompareTrendToBenchmark />
<BarCompareCategoryRanking />
<BarDistributionSummary />

---

# index

---
title: Bar chart
tab_title: Usage
description: Chart that uses rectangular bars to represent and compare values across different categories or groups.
meta_description: Learn how to implement bar charts to represent and compare values across different categories or groups.
thumbnail: assets/data-visualization/chart-components/bar-chart-sm.svg
keywords: ["Bar graph", "column graph"]
filter: 
    category: 
      - trend
      - ranking
related: 
    charts:
      - design-visualization-guidelines/overview
      - charts/line-chart
side_nav_order: 1
---

Bar charts use rectangular bars to represent values across different categories or groups. The height or length of each bar represents the numeric value for its category.
<br/>
Also known as: Bar graph, column graph.

## Anatomy

<img src="https://design.visa.com/assets/data-visualization/usage/bar-chart/bar-anatomy.svg" 
  alt="A vertical bar chart displaying monthly data with values ranging from 1.8k to 4.5k. Callout A indicating the optional title, callout B indicating the optional data table button, callout C indicating the required keyboard instructions, callout D indicating the optional subtitle, callout E indicating the required plot canvas, callout F indicating the required data markers, callout G indicating the quantitative axis, and callout H indicating the categorical axis"
/>

**A. Title (optional):** Brief text summarizing the contents of the chart.<br/>
**B. Data table button (optional):** UI icon button enabling users to view the chart's data in table format.<br/>
**C. Keyboard instructions (required):** UI icon button enabling users to access the chart's keyboard navigation instructions.<br/>
**D. Subtitle (optional):** Additional text providing details, context, or instructions about the chart.<br/>
**E. Plot canvas (required):** Area containing the graphic part of the chart including axes, gridlines, and other elements.<br/>
**F. Data markers (required):** Bars representing data points where the length or height of the bar indicates its category's value.<br/>
**G. Quantitative axis (required):** Scale representing numeric values, either on the horizontal or vertical axis.<br/>
**H. Categorical axis (required):** Scale representing categories or dates, either on the horizontal or vertical axis.<br/>

## Usage

A table that displays when to use and when not to use different component variants.

- When to use: To show how trends change over longer time periods, like weeks, months, or quarters.
- When not to use: To compare trends over very short time periods, like days or hours. Consider using a [line chart](https://design.visa.com/data-visualization/charts/line-chart) instead.<br/><br/>When showing continuous changes over time. Consider using a [line chart](https://design.visa.com/data-visualization/charts/line-chart) instead.

- When to use: To show the precise value of each data point.
- When not to use: If your data includes extreme values that distort the scale. Consider using a distribution insight chart instead.

- When to use: To compare ranking across categories and quickly identify the highest and lowest values.
- When not to use: If summarizing your data into categories would hide meaningful patterns.<br/><br/>If you need to show composition within categories. Consider using a composition insight chart, such as stacked bar or clustered bar chart instead.

<br/>

## Best practices

- Ensure the chart clearly communicates important takeaways, like if the data values are in a desirable or undesirable range.
- Always start the quantitative axis at zero to avoid distorting data or exaggerating differences in bar sizes. 
- Avoid displaying too many data points as this makes bar charts difficult to read and interpret. 
- Consider using [Pagination](https://design.visa.com/components/pagination) or group data into broader categories to limit how many data points are shown at a time.
- Provide in-context cues and labels to help users interpret the chart correctly without requiring significant effort. 

### Layouts

Bar charts can be displayed vertically or horizontally based on the data included. Select whichever layout will provide better legibility and scannability.

  
    #### Vertical layout
    <Typography>
      In this layout, bars are displayed next to one another with taller bars representing higher values.
    </Typography>
      <img src="https://design.visa.com/assets/data-visualization/usage/bar-chart/listbox-mark-required.svg" 
        alt="A vertical bar chart schematic."
      />
      - Use this layout to visualize trends, where each bar represents a date period such as week or month.
      - Use this layout when data has a meaningful order, like age groups or a scale (low, medium, high). 
  
  
    #### Horizontal layout
    <Typography>
      In this layout, bars are displayed along the horizontal axis with longer bars representing higher values.
    </Typography>
      <img src="https://design.visa.com/assets/data-visualization/usage/bar-chart/input-asterisk.svg" alt="A horizontal bar chart schematic."/>
      - Use this layout for data with distinct categories, such as countries or market segments.
      - Use this layout to help make longer category names easier to read.
  

### Data order

Bars on the categorical axis should be arranged in a meaningful way to help users quickly grasp the point of the chart. When deciding on the data order, consider what would be the most useful reading order of the data, as well as the story being told.
- Use standard ordering for categories that are chronological, like days, months, or years, if the goal is to visualize changes over time. 
- Sort categories in order of their values to emphasize ranking or the differences in quantities between categories.

### Chart size
Chart size should be based on the data within each chart. Use the columns in the [Responsive grid system](https://design.visa.com/base-elements/responsive-grid-system) to set the width of the card, as shown below. Adjust the card's height so it is proportional and accurately represents the shape of the data. 

<img src="https://design.visa.com/assets/data-visualization/usage/bar-chart/bar-chart-size-with-grid-overlay.svg" 
  alt="A content card with a bar chart placed over a grid schematic layout."
/>

- Ensure charts are wide enough to be interpreted without scrolling or zooming. 
- Consider the type of analysis users need to do with the chart, and ensure it’s large enough to support that goal.

### Color

Color can be used to emphasize meaningful information and draw attention to the most important information in a chart. Use one color from the [Neutral data visualization color palette (internal only)](https://dataexperience.visa.com/design-guide/color#What_to_do_when_color_has_no_meaning), unless encoding additional data with color would add significant value.
- Color should never be used alone to communicate meaning. For more, visit [Accessibility](https://design.visa.com/data-visualization/charts/bar-chart/accessibility). 
- Learn more about using color for data visualization in the [Color guidelines (internal only)](https://dataexperience.visa.com/design-guide/color).

## Content
- Always use sentence case except for proper nouns or acronyms.
- Use plain language and avoid abbreviations or jargon.
- Provide more detailed explanations and definitions for any complex metrics if needed.
- Reference [Content](https://design.visa.com/content) for additional guidance on crafting content within apps and experiences. 

### Titles and subtitles
- Use clear, informative titles to help users understand the chart’s topic and key takeaways.
- Frame titles as a headline that summarizes the trend or insight.
- Use subtitles to add more detail about the data being shown and help users understand how to interpret the chart.
- Consider phrasing titles or subtitles as questions to guide the user’s analysis, especially on exploratory dashboards where users are likely to spend significant time analyzing data. 
- Avoid titles and subtitles that are too general or vague.

### Labels

- Ensure numbers, dates, and other data or axis labels are formatted consistently.
- Follow plain language principles, such as using shorter and simpler words and phrases.

#### Number format

Simplify number formats to remove unnecessary details and reduce the mental effort needed to compare numbers. If needed, provide higher-precision numbers in a tooltip for users who want more information.

A table that displays recommended number formats for different data types.

- Data type: Use abbreviated format, such as 1.2k instead of 1,200.

- Data type: Use whole percentage points, except for special cases where basis points are needed.

- Data type: Use basis points (bps) when change percentage is very small. 1 bps equals 0.01% (0.0001 in decimal format).

- Data type: Round to the appropriate level of detail  that is required for the analysis. For example, for U.S. currency round to the nearest dollar amount.



---

# accessibility

---
title: Dumbbell plot
description: Chart comparing the difference between two related variables across multiple categories or date periods.
meta_description: Find accessibility guidelines for dumbbell plots to compare two related variables across multiple categories.
tab_title: Accessibility
tab_order: 1
---

This chart component has built-in accessibility features to support creating accessible charts from the start. These include descriptive tag properties, keyboard navigation controls, and tools to ensure sufficient color contrast. Find accessibility guidance below.

## Best practices 

Ensure the following best practices are met when implementing this component to create accessible data experiences for everyone, everywhere.

### Make thoughtful color choices

Ensure users of all abilities can understand the meaning of colors in your data visualization. Choose color combinations that provide sufficient contrast and add textures to support color-blind and low vision users.
#### Use accessible color palettes
Our data visualization color palettes are designed to ensure that data distinctions remain clear for users with various types of color vision deficiencies. Use this functionality to ensure sufficient contrast between colors and avoid relying only on color to differentiate categories or values. <br/><br/>For example, the Visa red to green divergent color palette ensures that all shades are seen as different values, even under different color-blindness simulators. Meanwhile, a default red to green color palette doesn’t make the shades distinct enough across the full range of the palette.

#### Outline light objects
Our chart components automatically add darker outlines to light-colored chart elements to ensure contrast and visibility against backgrounds and adjacent marks. Overriding this default behavior can make elements harder to distinguish from the chart background and reduce readability.

### Write clear alternative text

Use the chart components’ descriptive tag properties to provide concise and informative alternative text for screen readers. 

A table that provides guidance for writing chart accessibility properties.

- Accessibility property: Summarize what the chart shows and the type of data.<br/><br/>
Use simple language for straightforward charts. Describe the layout for uncommon chart types.<br/><br/>
Avoid repeating the chart title or subtitle.
- Guidance: “This bar chart shows monthly payment volume for this year compared to last year.”<br/><br/>
“This strip chart displays transaction volume across major European cities, with each city represented by a circle placed according to spending volume.”

- Accessibility property: Clearly state the takeaway and highlight key statistical insights and trends.<br/><br/>
Group data points to show patterns or outliers.<br/><br/>
Do not list numbers without explaining their meaning.
- Guidance: “Sales numbers increased every month except June and July.”<br/><br/>
“Europe and Asia Pacific had over 5% growth, while Asia Pacific lagged the global average at 1%.”

- Accessibility property: Explain which controls or filters affect the chart.<br/><br/>
Communicate any selections that have been applied to exclude or change the displayed data.
- Guidance: “The values in this chart are based on the filter selections applied to the dashboard.”

<br/>

### Add descriptive labels for data

Use the chart components’ custom labeling options to provide clear and descriptive names for displayed data. Labels like “num_transactions” may work during analysis, but “Number of transactions” is easier for users to understand and interpret.
#### Data labels
Data labels are the textual representations of data values in charts or tables. Use descriptive labels when presenting data to end users to provide clarity and avoid technical jargon or shorthand that may confuse non-technical audiences.
#### Tooltips
Tooltips add contextual information about data points when users hover or focus on chart elements. Clear and descriptive labels in tooltips help users understand the meaning of the data without requiring knowledge of internal naming conventions.

## Keyboard controls

Keyboard actions and their corresponding behaviors for dumbbell plots

<br/>



---

# code

---
title: Dumbbell plot
description: Chart comparing the difference between two related variables across multiple categories or date periods.
meta_description: Get code for dumbbell plots to compare two related variables across multiple categories.
tab_title: Code
tab_order: 3
thumbnail: assets/flows/fileupload-graphic.svg
show_table_of_contents: true
---

<ChartsCodeExampleList
	client:only="react"
	chartExampleId="dumbbell-plot-trend-with-categories"
	chartTag="dumbbell-plot"
/>

<br></br><br></br>


---

# examples

---
title: Dumbbell plot
description: Chart comparing the difference between two related variables across multiple categories or date periods.
meta_description: Explore examples of dumbbell plots to compare two related variables across multiple categories.
tab_title: Examples
tab_order: 2
thumbnail: assets/flows/fileupload-graphic.svg
---

Explore our dumbbell plot examples to see how the VCC dumbbell plot component can be customized for specific business scenarios and analysis tasks.
<br/>
Find design assets for these dumbbell plot examples in our Figma [Data Experience Charts (internal only)](https://bookmarks.visa.com/vpds-data-experience-charts) library.

<DumbbellPlotTrendWithCategories />
<DumbbellPlotCompareCurrentVsPrevious />
<DumbbellPlotCompareTrendToBenchmark />


---

# index

---
title: Dumbbell plot
description: Chart comparing the difference between two related variables across multiple categories or date periods.
meta_description: Learn how to use dumbbell plots to compare two related variables across multiple categories.
tab_title: Usage
thumbnail: assets/data-visualization/chart-components/dumbbell-sm.svg
keywords: ["Barbell chart", "connected dot plot"]
filter: 
    category: 
        - deviation
        - trend
related:
    charts:
        - design-visualization-guidelines/overview
        - charts/line-chart
side_nav_order: 2
---

Dumbbell plots use dots connected by lines to compare the values of two series of data. The position of the dots represents the numeric values, with the length of the line showing the difference or gap between the data series.
<br/>
Also known as: Barbell chart, connected dot plot.

## Anatomy

<img src="https://design.visa.com/assets/data-visualization/usage/dumbbell-plot/dumbbell-anatomy.svg" alt="A dumbbell plot displaying monthly data with values. Callout A indicating the optional title, callout B indicating the optional data table button, callout C indicating the required keyboard instructions, callout D indicating the optional subtitle, callout E indicating the optional legend, callout F indicating the required plot canvas, callout G indicating the required data markers, callout H indicating the required vertical axis, and callout I indicating the required horizontal axis"/>

**A. Title (optional):** Brief text summarizing the contents of the chart.<br/>
**B. Data table button (optional):** UI icon button enabling users to view the chart's data in table format.<br/>
**C. Keyboard instructions (required):** UI icon button enabling users to access the chart's keyboard navigation instructions.<br/>
**D.  Subtitle (optional):** Additional text providing details, context, or instructions about the chart.<br/>
**E. Legend (optional):** Area explaining the meaning of each dot in the dumbbell plot to help users interpret the chart.<br/>
**F. Plot canvas (required):** Area containing the graphic part of the chart including axes, gridlines, and other elements.<br/>
**G. Data markers (required):** Dots connected by lines representing two data series and the difference between them.<br/>
**H. Vertical axis (required):** Scale representing numeric values.<br/>
**I. Horizontal axis (required):** Scale representing a date period or a category.<br/>

## Usage

A table that displays when to use and when not to use different component variants.

- When to use: To compare two related values for each category or time period (e.g., actual vs. target, current vs. previous).
- When not to use: When there are more than two values per category, as the chart becomes cluttered. Consider using clustered or stacked bar chart instead.

- When to use: To highlight the size of the gap or difference between two categories.
- When not to use: When precise trends for each category are more important than the difference. Consider using a [line chart](https://design.visa.com/data-visualization/charts/line-chart) instead.

- When to use: When the goal is to show how differences change across categories or over time.
- When not to use: When gaps between values are too small or not meaningful, making the visual comparison ineffective.

- When to use: To emphasize relative performance against a benchmark or paired value.
- When not to use: If there’s no benchmark or paired value to compare. Consider using a [bar chart](https://design.visa.com/data-visualization/charts/bar-chart) instead.

<br/>

## Content

- Always use sentence case except for proper nouns or acronyms.
- Use plain language and avoid abbreviations or jargon.
- Provide more detailed explanations and definitions for any complex metrics if needed.
- Reference [Content](https://design.visa.com/content) for additional guidance on crafting content within apps and experiences. 

### Titles and subtitles

- Use clear, informative titles to help users understand the chart’s topic and key takeaways.
- Frame titles as a headline that summarizes the trend or insight.
- Use subtitles to add more detail about the data being shown and help users understand how to interpret the chart.
- Consider phrasing titles or subtitles as questions to guide the user’s analysis, especially on exploratory dashboards where users are likely to spend significant time analyzing data. 
- Avoid titles and subtitles that are too general or vague.

### Labels

- Ensure numbers, dates, and other data or axis labels are formatted consistently.
- Follow plain language principles, such as using shorter and simpler words and phrases.

#### Number format
          
Simplify number formats to remove unnecessary details and reduce the mental effort needed to compare numbers. If needed, provide higher-precision numbers in a tooltip for users who want more information.

A table that displays recommended number formats for different data types.

- Data type: Use abbreviated format, such as 1.2k instead of 1,200.

- Data type: Use whole percentage points, except for special cases where basis points are needed.

- Data type: Use basis points (bps) when change percentage is very small. 1 bps equals 0.01% (0.0001 in decimal format).

- Data type: Round to the appropriate level of detail  that is required for the analysis. For example, for U.S. currency round to the nearest dollar amount.



---

# accessibility

---
title: Heatmap
description: Chart where each cell represents the value of the category pairing to show most  and least common combinations of values within a matrix.
meta_description: Find accessibility guidelines for heatmaps to to show the size of values within a matrix.
tab_title: Accessibility
tab_order: 1
---

This chart component has built-in accessibility features to support creating accessible charts from the start. These include descriptive tag properties, keyboard navigation controls, and tools to ensure sufficient color contrast. Find accessibility guidance below.

## Best practices 

Ensure the following best practices are met when implementing this component to create accessible data experiences for everyone, everywhere.

### Make thoughtful color choices

Ensure users of all abilities can understand the meaning of colors in your data visualization. Choose color combinations that provide sufficient contrast and add textures to support color-blind and low vision users.
#### Use accessible color palettes
Our data visualization color palettes are designed to ensure that data distinctions remain clear for users with various types of color vision deficiencies. Use this functionality to ensure sufficient contrast between colors and avoid relying only on color to differentiate categories or values. <br/><br/>For example, the Visa red to green divergent color palette ensures that all shades are seen as different values, even under different color-blindness simulators. Meanwhile, a default red to green color palette doesn’t make the shades distinct enough across the full range of the palette.

#### Outline light objects
Our chart components automatically add darker outlines to light-colored chart elements to ensure contrast and visibility against backgrounds and adjacent marks. Overriding this default behavior can make elements harder to distinguish from the chart background and reduce readability.

### Write clear alternative text

Use the chart components’ descriptive tag properties to provide concise and informative alternative text for screen readers. 

A table that provides guidance for writing chart accessibility properties.

- Accessibility property: Summarize what the chart shows and the type of data.<br/><br/>
Use simple language for straightforward charts. Describe the layout for uncommon chart types.<br/><br/>
Avoid repeating the chart title or subtitle.
- Guidance: “This bar chart shows monthly payment volume for this year compared to last year.”<br/><br/>
“This strip chart displays transaction volume across major European cities, with each city represented by a circle placed according to spending volume.”

- Accessibility property: Clearly state the takeaway and highlight key statistical insights and trends.<br/><br/>
Group data points to show patterns or outliers.<br/><br/>
Do not list numbers without explaining their meaning.
- Guidance: “Sales numbers increased every month except June and July.”<br/><br/>
“Europe and Asia Pacific had over 5% growth, while Asia Pacific lagged the global average at 1%.”

- Accessibility property: Explain which controls or filters affect the chart.<br/><br/>
Communicate any selections that have been applied to exclude or change the displayed data.
- Guidance: “The values in this chart are based on the filter selections applied to the dashboard.”

<br/>

### Add descriptive labels for data

Use the chart components’ custom labeling options to provide clear and descriptive names for displayed data. Labels like “num_transactions” may work during analysis, but “Number of transactions” is easier for users to understand and interpret.
#### Data labels
Data labels are the textual representations of data values in charts or tables. Use descriptive labels when presenting data to end users to provide clarity and avoid technical jargon or shorthand that may confuse non-technical audiences.
#### Tooltips
Tooltips add contextual information about data points when users hover or focus on chart elements. Clear and descriptive labels in tooltips help users understand the meaning of the data without requiring knowledge of internal naming conventions.

## Keyboard controls

Keyboard actions and their corresponding behaviors for heatmaps

<br/>


---

# code

---
title: Heatmap
description: Chart where each cell represents the value of the category pairing to show most  and least common combinations of values within a matrix.
meta_description: Get code for heatmaps to show the size of values within a matrix.
tab_title: Code
tab_order: 3
show_table_of_contents: true
---

<ChartsCodeExampleList
	client:only="react"
	chartExampleId="heatmap-category-pattern-analysis"
	chartTag="heatmap"
/>

<br></br><br></br>


---

# examples

---
title: Heatmap
description: Chart where each cell represents the value of the category pairing to show most  and least common combinations of values within a matrix.
meta_description: Explore examples of heatmaps to to show the size of values within a matrix.
tab_title: Examples
tab_order: 2
---

Explore our heatmap examples to see how the VCC heatmap component can be customized for specific business scenarios and analysis tasks.
<br/>
Find design assets for these heatmap examples in our Figma [Data Experience Charts (internal only)](https://bookmarks.visa.com/vpds-data-experience-charts) library.

<HeatMapCategoryPatternAnalysis />
<HeatMapCorrelationMatrix />
<HeatmapSeasonalPatternAnalysis />
<HeatMapCategoryShareOfTotal />

---

# index

---
title: Heatmap
description: Chart where each cell shows the value of a category pairing, highlighting the most and least common combinations.
meta_description: Learn how to use heatmaps to show the size of values within a matrix.
tab_title: Usage
thumbnail: assets/data-visualization/chart-components/heatmap-sm.svg
keywords: ["Highlight table", "matrix chart", "mosaic plot", "density plot"]
filter: 
    category: 
        - correlation
related: 
    charts: 
        - design-visualization-guidelines/overview
        - charts/bar-chart
side_nav_order: 2
---

Heatmaps use a grid of colored cells to represent numeric values at the intersection of two categories. Rows and columns represent values of the categorical variables, using colors to represent the numeric value for each category pairing and reveal the most and least common combinations.
<br/>
Also known as: Highlight table, matrix chart, mosaic plot, density plot.

## Anatomy

<img src="https://design.visa.com/assets/data-visualization/usage/heatmap/heatmap-anatomy.svg" alt="A heatmap displaying weekly data with values ranging from 66 to 130. Callout A indicating the optional title, callout B indicating the optional data table button, callout C indicating the required keyboard instructions, callout D indicating the optional subtitle, callout E indicating the required plot canvas, callout F indicating the required data markers, callout G indicating the required vertical axis, callout H indicating the required horizontal axis, and callout I indicating the optional legend"/>

**A. Title (optional):** Brief text summarizing the contents of the chart.<br/>
**B. Data table button (optional):** UI icon button enabling users to view the chart's data in table format.<br/>
**C. Keyboard instructions (required):** UI icon button enabling users to access the chart's keyboard navigation instructions.<br/>
**D. Subtitle (optional):** Additional text providing more details.<br/>
**E. Plot canvas (required):** Area containing the graphic part of the chart including heatmap cells, axes, and other elements.<br/>
**F. Data markers (required):** Colored cells representing the numeric value for a category pairing.<br/> 
**G. Vertical axis (required):** Scale representing a category, group, or date period.<br/>
**H. Horizontal axis (required):** Scale representing a category, group, or date period.<br/>
**I. Legend (optional):** Explains how to interpret the color scale used in the heatmap cells.<br/>

## Usage

A table that displays when to use and when not to use different component variants.

- When to use: To show patterns or clusters in data visually, making it easy to spot high and low values.
- When not to use: When precise comparisons between individual data points are required. Consider using a [bar chart](https://design.visa.com/data-visualization/charts/bar-chart) or dot plot instead.

- When to use: To summarize large numeric datasets across two dimensions (e.g., categories or time intervals).
- When not to use: When the dataset has extreme outliers that distort the color scale. Consider using a [dumbbell plot](https://design.visa.com/data-visualization/charts/dumbbell-plot) instead.

- When to use: When the goal is to highlight variation and distribution rather than precise individual values.
- When not to use: When the numeric variable shows little variation, as color differences will be hard to interpret. Consider using a [bar chart](https://design.visa.com/data-visualization/charts/bar-chart) instead.

- When to use: To quickly identify correlations or relationships between variables.
- When not to use: When comparing too many categories, which can make the heatmap cluttered. Consider grouping or filtering categories.

<br/>

## Best practices
- Include a legend unless data labels are included in every cell.

## Content

- Always use sentence case except for proper nouns or acronyms.
- Use plain language and avoid abbreviations or jargon.
- Provide more detailed explanations and definitions for any complex metrics if needed.
- Reference [Content](https://design.visa.com/content) for additional guidance on crafting content within apps and experiences. 

### Titles and subtitles

- Use clear, informative titles to help users understand the chart’s topic and key takeaways.
- Frame titles as a headline that summarizes the trend or insight.
- Use subtitles to add more detail about the data being shown and help users understand how to interpret the chart.
- Consider phrasing titles or subtitles as questions to guide the user’s analysis, especially on exploratory dashboards where users are likely to spend significant time analyzing data. 
- Avoid titles and subtitles that are too general or vague.

### Labels

- Ensure numbers, dates, and other data or axis labels are formatted consistently.
- Follow plain language principles, such as using shorter and simpler words and phrases.

#### Number format

Simplify number formats to remove unnecessary details and reduce the mental effort needed to compare numbers. If needed, provide higher-precision numbers in a tooltip for users who want more information.

A table that displays recommended number formats for different data types.

- Data type: Use abbreviated format, such as 1.2k instead of 1,200.

- Data type: Use whole percentage points, except for special cases where basis points are needed.

- Data type: Use basis points (bps) when change percentage is very small. 1 bps equals 0.01% (0.0001 in decimal format).

- Data type: Round to the appropriate level of detail  that is required for the analysis. For example, for U.S. currency round to the nearest dollar amount.



---

# accessibility

---
title: Line chart
description: Chart showing points connected by line segments, used to represent how a number changes over time.
meta_description: Find accessibility guidelines for line charts used to represent how a number changes over time.
tab_title: Accessibility
tab_order: 1
---

This chart component has built-in accessibility features to support creating accessible charts from the start. These include descriptive tag properties, keyboard navigation controls, and tools to ensure sufficient color contrast. Find accessibility guidance below.

## Best practices 

Ensure the following best practices are met when implementing this component to create accessible data experiences for everyone, everywhere.

### Make thoughtful color choices

Ensure users of all abilities can understand the meaning of colors in your data visualization. Choose color combinations that provide sufficient contrast and add textures to support color-blind and low vision users.
#### Use accessible color palettes
Our data visualization color palettes are designed to ensure that data distinctions remain clear for users with various types of color vision deficiencies. Use this functionality to ensure sufficient contrast between colors and avoid relying only on color to differentiate categories or values. <br/><br/>For example, the Visa red to green divergent color palette ensures that all shades are seen as different values, even under different color-blindness simulators. Meanwhile, a default red to green color palette doesn’t make the shades distinct enough across the full range of the palette.

#### Add contrast with textures
Textures help differentiate categories when color doesn’t provide enough contrast. Use the texture fill option in our bar charts to improve accessibility for users with color vision deficiencies and maintain clarity when charts are printed in grayscale.

#### Outline light objects
Our chart components automatically add darker outlines to light-colored chart elements to ensure contrast and visibility against backgrounds and adjacent marks. Overriding this default behavior can make elements harder to distinguish from the chart background and reduce readability.

### Write clear alternative text

Use the chart components’ descriptive tag properties to provide concise and informative alternative text for screen readers. 

A table that provides guidance for writing chart accessibility properties.

- Accessibility property: Summarize what the chart shows and the type of data.<br/><br/>
Use simple language for straightforward charts. Describe the layout for uncommon chart types.<br/><br/>
Avoid repeating the chart title or subtitle.
- Guidance: “This bar chart shows monthly payment volume for this year compared to last year.”<br/><br/>
“This strip chart displays transaction volume across major European cities, with each city represented by a circle placed according to spending volume.”

- Accessibility property: Clearly state the takeaway and highlight key statistical insights and trends.<br/><br/>
Group data points to show patterns or outliers.<br/><br/>
Do not list numbers without explaining their meaning.
- Guidance: “Sales numbers increased every month except June and July.”<br/><br/>
“Europe and Asia Pacific had over 5% growth, while Asia Pacific lagged the global average at 1%.”

- Accessibility property: Explain which controls or filters affect the chart.<br/><br/>
Communicate any selections that have been applied to exclude or change the displayed data.
- Guidance: “The values in this chart are based on the filter selections applied to the dashboard.”

<br/>

### Add descriptive labels for data

Use the chart components’ custom labeling options to provide clear and descriptive names for displayed data. Labels like “num_transactions” may work during analysis, but “Number of transactions” is easier for users to understand and interpret.
#### Data labels
Data labels are the textual representations of data values in charts or tables. Use descriptive labels when presenting data to end users to provide clarity and avoid technical jargon or shorthand that may confuse non-technical audiences.
#### Tooltips
Tooltips add contextual information about data points when users hover or focus on chart elements. Clear and descriptive labels in tooltips help users understand the meaning of the data without requiring knowledge of internal naming conventions.

## Keyboard controls

Keyboard actions and their corresponding behaviors for line charts

- Key: Enter the chart area/drill down a level on the chart area or a line.

- Key: Drill up a level on a line or a point.

- Key: Move among sibling lines or points when focusing on a line or a point.

- Key: Move among points across lines when focusing on a line or a point.

- Key: Press and hold when using the arrow keys for the best navigation experience on a Mac (VoiceOver).

- Key: Dismiss the tooltip at any time.

- Key: Exit the chart at any time.

<br/>



---

# code

---
title: Line chart
description: Chart showing points connected by line segments, used to represent how a number changes over time.
meta_description: Get code for line charts used to represent how a number changes over time.
tab_title: Code
tab_order: 3
show_table_of_contents: true
---

<ChartsCodeExampleList
	client:only="react"
	chartExampleId="line-chart-trend-with-categories"
	chartTag="line-chart"
/>

<br></br><br></br>

---

# examples

---
title: Line chart
description: Chart showing points connected by line segments, used to represent how a number changes over time.
meta_description: Explore examples of line charts used to represent how a number changes over time.
tab_title: Examples
tab_order: 2
---

Explore our line chart examples to see how the VCC line chart component can be customized for specific business scenarios and analysis tasks.
<br/>
Find design assets for these line chart examples in our Figma [Data Experience Charts (internal only)](https://bookmarks.visa.com/vpds-data-experience-charts) library.

<LineChartTrendWithCategories />
<LineChartCurrentVsPreviousTrend />
<LineChartCompareTrendToBenchmark />
<LineChartOneVsAll />


---

# index

---
title: Line chart
description: Chart showing points connected by line segments, used to represent how a number changes over time.
meta_description: Learn how to use line charts to represent how a number changes over time.
tab_title: Usage
thumbnail: assets/data-visualization/chart-components/line-chart-sm.svg
keywords: ["Line graphs", "time series charts"]
filter: 
    category: 
        - trend
related: 
    charts: 
        - design-visualization-guidelines/overview
        - charts/bar-chart
side_nav_order: 4
---

Line charts use points connected by line segments to represent how a number changes over time. The direction and slope of each line segment reveals the rate of change between data points, making it easy to identify trends and fluctuations.
<br/>
Also known as: Line graphs, time series charts.

## Anatomy

<img src="https://design.visa.com/assets/data-visualization/usage/line-chart/line-anatomy.svg" alt="The image displays a line chart with two data series plotted over a period from January to November. Callout A indicating the optional title, callout B indicating the optional data table button, callout C indicating the required keyboard instructions, callout D indicating the optional subtitle, callout E indicating the required plot canvas, callout F indicating the optional series labels, callout G indicating the required vertical axis, callout H indicating the required data markers, and callout I indicating the required horizontal axis"/>

**A. Title (optional):** Brief text summarizing the contents of the chart.<br/>
**B. Data table button (optional):** UI icon button enabling users to view the chart's data in table format.<br/>
**C. Keyboard instructions (required):** UI icon button enabling users to access the chart's keyboard navigation instructions.<br/>
**D. Subtitle (optional):** Additional text providing details, context, or instructions about the chart.<br/>
**E. Plot canvas (required):** Area containing the graphic part of the chart including axes, gridlines, and other elements.<br/>
**F. Series labels (optional):** Text that identifies each line's category.<br/>
**G. Vertical axis (required):** Scale representing a continuous numeric variable.<br/>
**H. Data markers (required):** Dots representing individual data points and lines representing the relationships between points.<br/>
**I. Horizontal axis (required):** Scale representing a date variable.<br/>

## Usage

A table that displays when to use and when not to use different component variants.

- When to use: To show how values change over time or across a continuous sequence.
- When not to use: If the individual values are more important than the overall trend. Consider using a [bar chart](https://design.visa.com/data-visualization/charts/bar-chart) instead.

- When to use: To emphasize overall patterns and trends rather than individual data points.
- When not to use: If the horizontal axis contains categorical or non-sequential data, since line charts imply continuity.

- When to use: To illustrate the rate and direction of change between data points.
- When not to use: If comparing more than five categories which can make the chart cluttered. Consider grouping or using alternative charts.

- When to use: For longer time series where the shape of the trend matters more than exact values.
- When not to use: If the focus is on composition within categories. Consider using a stacked or clustered bar chart instead.

<br/>

## Best practices
- Select the right chart variant to emphasize the most important takeaways.
- Provide clear explanations, labels and annotations to highlight key data points and help users interpret important findings.
- Always use straight line segments for the most accurate interpretation of data points and trends.
- Use a range of values for the vertical axis that accurately represent the trend and doesn't exaggerate differences between data points. 
- Avoid starting the vertical axis at zero when the minimum value in the dataset is significantly higher.
- Select consistent and meaningful intervals for the horizontal axis to ensure the rate of change is represented accurately. 
- Avoid displaying too many data points or lines that could overwhelm users and make the chart difficult to interpret. 

### Chart size
Chart size should be based on the data within each chart. Use the columns in the [Responsive grid system](https://design.visa.com/base-elements/responsive-grid-system) to set the width of the card, as shown below. Adjust the card’s height so the is proportional and accurately represents the shape of the data. 
- Ensure charts are wide enough to be interpreted without scrolling or zooming. 

<img src="https://design.visa.com/assets/data-visualization/usage/line-chart/size.png" 
  alt="A content card with a line chart placed over a grid schematic layout."
  class="chart-usage-img-margin-block-end-0"
/>

### Color
Color can be used to emphasize meaningful information and draw attention to the most important information in a chart.
- Color should never be used alone to communicate meaning. For more, visit [Accessibility](https://design.visa.com/data-visualization/charts/line-chart/accessibility). 
- Learn more about using color for data visualization in the [Color guidelines (internal only)](https://bookmarks.visa.com/vpds-neutral-data-visualization-color-palette)

### Data marker dots
Data markers represent individual data points and can show the progression between points. Users can choose to show or hide data markers with the optional “show dots” feature. 
- Choose dot sizes that allow the lines to remain visible and complement the chart without overwhelming it.

<img src="https://design.visa.com/assets/data-visualization/usage/line-chart/data-marker.png" 
  alt="A line chart with data marker dots."
  class="chart-usage-img-margin-block-end-0"
  />

{/* ### Represent data accurately

Help users avoid misinterpretations of line charts by ensuring  clear communication of data point values and minimizing perception issues that can be caused by lines.

- Select consistent and meaningful date intervals for the horizontal axis, to ensure rate of change is accurately represented. 
- Select a range of values for the vertical axis that is large enough to prevent exaggeration of minor changes while still allowing users to see meaningful variation in the data. This ensures that the data representation remains true to the actual trends and patterns.
- Avoid starting the vertical axis at zero when the minimum value in the dataset is significantly higher.
- Be transparent about missing, unknown, or estimated data, to help users understand the limitations of the data and prevent misinterpretations.
- Avoid using curved line styles, which can distort the perception of data values. Straight line segments enable more accurate interpretation of data points and trends.

##### Show vs hide data marker dots

Show dots is an optional feature that allows users to control the visibility of data marker dots. 

  
      <img src="https://design.visa.com/assets/data-visualization/usage/line-chart/data-marker.png" alt="A line chart with data marker dots."/>
      - Include data marker dots to provide a clear visual reference for the location of data points along the line, representing specific values in the dataset.
      - Balance visibility of dots and lines by selecting a dot radius size that complements the chart without overwhelming it.
  
  
      <img src="https://design.visa.com/assets/data-visualization/usage/line-chart/data-marker-alt.png" alt="A line chart with selective data marker dots."/>
      - Depending on the key analysis tasks and the volume of data to be displayed, consider using data marker dots selectively to emphasize critical data points.
      - Use dot size and formatting to establish a strong visual focus for the chart.
  
 */}

### Handling missing data
Communicate gaps in the data in a clear and consistent way to help users quickly identify where data is missing and understand its limitations. If a data point is missing, don’t connect the points before and after the gap to ensure it’s clear that no data exists between those data points.
- Be transparent about missing, unknown, or estimated data to help users understand the limitations of the data and prevent misinterpretations.

<img src="https://design.visa.com/assets/data-visualization/usage/line-chart/missing-data.png" 
  alt="A line chart with missing data points."
  class="chart-usage-img-margin-block-end-0"
/>

### Direct labeling
Direct labeling refers to placing labels near each data point to communicate precise values. Use direct labeling for data points and line series to make it easier for users to interpret line charts. There are three types of labels in line charts: Data point labels, axis labels, and line series labels.
- Ensure labels don’t clutter the chart or distract from the data by keeping labels short and following number format guidelines.

  
    #### Data point labels
      Show labels as close as possible to the data points they represent to reduce the need for users to look back and forth between the chart and the axis labels.
      <img src="https://design.visa.com/assets/data-visualization/usage/line-chart/data-labels.png" alt="A line chart with all data points labelled placed over the data point maker."/>
      - Label all data points when users should know the specific value of each point.
      - Consider hiding the y-axis if you’re showing all data labels.
  
  
    #### Axis labels
      Show axis labels to help users estimate values for unlabeled data points. Use this method when trends are more helpful than individual values. 
      <img src="https://design.visa.com/assets/data-visualization/usage/line-chart/axis-labels.png" alt="A line chart with axis labels."/>
      - Use axis labels when directly labeling every data point would overcrowd or obscure the chart.
  
 

#### Line series labels
When a line chart includes multiple line series, ensure users can identify what each line represents. There are generally two methods for this: Labeling lines directly or using a legend. 

#### Labeling each line
Directly labeling each line is the clearest method, as users can directly tell what the line represents.
<img src="https://design.visa.com/assets/data-visualization/usage/line-chart/series-labels.svg" 
  alt="A line chart with multiple series, each data point is labelled separately."
/>
- Show labels close to their lines to ensure users can identify what they refer to. 
- Consider hiding the color legend with this method to reduce unnecessary duplicate information.

#### Using a legend
Using a legend is an alternative method that can be helpful when there isn’t sufficient space to label lines directly. 
<img src="https://design.visa.com/assets/data-visualization/usage/line-chart/legend.svg" 
  alt="A line chart with multiple series, legend is used to identify series."
/>
- Include a legend when directly labeling each line series isn't possible or would overcrowd the chart.
- Ensure the legend clearly indicates what each line represents using color, line styling, or similar methods.

## Content

- Always use sentence case except for proper nouns or acronyms.
- Use plain language and avoid abbreviations or jargon.
- Provide more detailed explanations and definitions for any complex metrics if needed.
- Reference [Content](https://design.visa.com/content) for additional guidance on crafting content within apps and experiences. 

### Titles and subtitles

- Use clear, informative titles to help users understand the chart’s topic and key takeaways.
- Frame titles as a headline that summarizes the trend or insight.
- Use subtitles to add more detail about the data being shown and help users understand how to interpret the chart.
- Consider phrasing titles or subtitles as questions to guide the user’s analysis, especially on exploratory dashboards where users are likely to spend significant time analyzing data. 
- Avoid titles and subtitles that are too general or vague.

### Labels

- Ensure numbers, dates, and other data or axis labels are formatted consistently.
- Follow plain language principles, such as using shorter and simpler words and phrases.

#### Number format

Simplify number formats to remove unnecessary details and reduce the mental effort needed to compare numbers. If needed, provide higher-precision numbers in a tooltip for users who want more information.

A table that displays recommended number formats for different data types.

- Data type: Use abbreviated format, such as 1.2k instead of 1,200.

- Data type: Use whole percentage points, except for special cases where basis points are needed.

- Data type: Use basis points (bps) when change percentage is very small. 1 bps equals 0.01% (0.0001 in decimal format).

- Data type: Round to the appropriate level of detail  that is required for the analysis. For example, for U.S. currency round to the nearest dollar amount.



---

# examples

---
title: Charts
description: Explore chart components and best practices for visualizing and communicating data insights.
meta_description: Explore our collection of chart examples tailored to support Visa’s most common business scenarios and analysis tasks.
full_width: true
tab_title: Examples index
page_size: large
show_table_of_contents: false
---

Explore our collection of chart examples, which have been tailored to support Visa’s most common business scenarios and analysis tasks.

<ChartExampleGrid />

---

# index

---
title: Charts
description: Explore usage, accessibility, and design best practices for visualizing and communicating data insights.
meta_description: Chart components are the building blocks for creating insightful, inclusive, and accessible data experiences for everyone, everywhere. 
page_size: large
full_width: true
tab_title: Charts index
side_nav_title: Overview
side_nav_additional_screenreader_title: for the Data Visualization chart components
thumbnail: assets/home/data-visualization-graphic.svg
side_nav_order: 0
show_table_of_contents: false
---

**Note:** Our guidelines currently only include these charts: bar chart, dumbbell plot, line chart, and heatmap. Generate charts directly in your design files with exportable code using our [Figma plugin (internal only)](https://bookmarks.visa.com/vpds-charts-playground-figma-plugin).

<br/>
Explore [Visa Charts Playground (internal only)](https://bookmarks.visa.com/vpds-charts-playground), a rapid prototyping workspace for data visualization. Browse our full library of 30+ chart patterns, customize datasets, and seamlessly transition from concept to code.

<ChartGrid />

---

# index

---
title: Data visualization principles
description: Gain insight into the data visualization principles that help create insightful and accessible data experiences.
meta_description: Gain insight into the data visualization principles that help create insightful and accessible data experiences.
side_nav_title: Data visualization principles
side_nav_order: 1
page_size: large
full_width: true
---

Learn about the five principles we use to provide effective data experiences for our users. They provide a consistent way to measure strengths and weaknesses in the design of Visa's data products.

<br /><br />

<FeatureWithIcon customWidth='50' customHeight='50' icon={VisaSearchHigh}>
  ## Principle #1: Findable
  <Typography variant="body-2" className="v-mb-16">Findable data experiences help users **navigate** the experience, **locate** information, and understand how to **interact** with​ your data.</Typography>
  <Typography variant="subtitle-1" className="v-mb-16">Questions to explore</Typography>
  * Does your data experience use effective **information architecture** to help users navigate and identify what information is or isn’t available?
  * Does the **visual hierarchy** of your experience support the key business question(s) by drawing attention to the most important elements?
  * How might the **data representation** or **chart selection** help users locate information and find insights?
  * Can users easily discover and understand the **interactivity** of your experience?
</FeatureWithIcon>

<FeatureWithIcon customWidth='50' customHeight='50' icon={VisaReportHigh}>
  ## Principle #2: Learnable
  <Typography variant="body-2" className="v-mb-16">Learnable data experiences help users predict how the experience works by using consistent **design and functionality**, providing **feedback and help options**, and matching **common mental models.** </Typography>
  <Typography variant="subtitle-1" className="v-mb-16">Questions to explore</Typography>
  * Do elements with a similar level of importance use the same **visual hierarchy?**
  * Can users accurately predict the behavior of **interactive elements** within the experience?
  * Does the **data representation** and **visual encoding** help users understand how to read and interpret the chart?
  * How could additional **context** like metaphors or annotations be used to make the numbers more memorable or understandable?
</FeatureWithIcon>

<FeatureWithIcon customWidth='50' customHeight='50' icon={VisaFullScreenHigh}>
  ## Principle #3: Focused and clear
  <Typography variant="body-2" className="v-mb-16">Focused and clear data experiences help users focus on what’s most important by **limiting distraction** and **directing attention.**</Typography>
  <Typography variant="subtitle-1" className="v-mb-16">Questions to explore</Typography>
  * Does your data experience use effective **information architecture** to provide navigation and flexibility that fits the user’s mental model?
  * How can **visual hierarchy** be used to emphasize key data and differentiate between items with different levels of importance?
  * How might **interactive features** be used to make it easier to identify specific data points, trends, or relationships?
  * How might we spark users’ curiosity with additional **context** or **visual encoding** without adding unnecessary detail?
</FeatureWithIcon>

<FeatureWithIcon customWidth='50' customHeight='50' icon={VisaCheckmarkHigh}>
  ## Principle #4: Trusted
  <Typography variant="body-2" className="v-mb-16">Trustworthy data experiences increase user engagement by incorporating **predictable patterns**, providing sources to **verify the credibility of the data**, and helping users **interpret data accurately.**</Typography>
  <Typography variant="subtitle-1" className="v-mb-16">Questions to explore</Typography>
  * Is information about the data source, accuracy, and scope communicated with **transparency?**
  * Does the **data representation**, including visual styling and color encoding, enhance the meaning of the chart without changing the accuracy of the data? 
  * Do **interactive elements** behave predictably and make data easier to interpret? 
  * Is there meaningful **context** provided for accurate interpretation of the key insights of the chart?
</FeatureWithIcon>

<FeatureWithIcon customWidth='50' customHeight='50' icon={VisaRewardHigh}>
  ## Principle #5: Valuable
  <Typography variant="body-2" className="v-mb-16">Valuable data experiences empower users by clearly **communicating the chart’s purpose**, delivering **actionable insights**, and enabling them to **answer key business questions.**</Typography>
  <Typography variant="subtitle-1" className="v-mb-16">Questions to explore</Typography>
  * Does the chart provide **actionable insights** relevant to the user’s business needs?
  * Does the **information structure** and **visual hierarchy** support the user’s main goal?
  * How could **labels** or **data representation** be used to add more meaning and emphasize the key purpose of the experience?
  * How might **interactive features** help users customize the display for more tailored analysis?
</FeatureWithIcon>



---

# index

---
title: Data visualization guidelines
description: Explore foundational principles and techniques for visualizing and communicating insights.
meta_description: Explore foundational principles and techniques for visualizing and communicating insights. 
page_size: full-width
side_nav_title: Overview
side_nav_additional_screenreader_title: for the Data Visualization design guidelines
thumbnail: assets/home/data-visualization-graphic.svg
side_nav_order: 0
show_table_of_contents: false
---

<LibraryCardListLarge>
    <LibraryCardLarge 
        title="Data visualization principles" 
        description="Gain insight into the data visualization principles that help create intuitive data experiences."
        href={`https://design.visa.com/data-visualization/design-visualization-guidelines/data-visualization-principles`} 
        thumbnail={`https://design.visa.com/assets/data-visualization/design-guidelines/data-viz-principles-graphic.svg`}
        hasChevron
        hoverColor={colorPink}
    />
    <LibraryCardLarge 
        title="Color palettes (internal only)" 
        description="Learn how to use Visa data visualization color palettes to create accessible and consistent data experiences. "
        href="https://bookmarks.visa.com/vpds-neutral-data-visualization-color-palette" 
        thumbnail={`https://design.visa.com/assets/data-visualization/design-guidelines/color-graphic.svg`}
        external
        aria-label={"Color palettes (internal only, opens in new tab)"}
        hoverColor={colorPink}
    />
    <LibraryCardLarge 
        title="Selecting a chart" description="Learn how to design charts and data visualizations to communicate insights and help your audience focus on the most important information."
        href={`https://design.visa.com/data-visualization/design-visualization-guidelines/selecting-a-chart`} 
        thumbnail={`https://design.visa.com/assets/data-visualization/design-guidelines/chart-design.svg`}
        hasChevron
        hoverColor={colorPink}
    />
</LibraryCardListLarge>

---

# index

---
title: Selecting a chart
description: Learn how to find the right chart for your audience's analysis needs.
meta_description: Learn how to find the right chart for your audience's analysis needs.
side_nav_title: Selecting a chart
side_nav_order: 2
---

Selecting the right chart requires determining the key purpose of the chart and tailoring it to your audience's needs.<br/><br/>
Start by understanding the chart types available in our system. Once you're familiar, you can select a chart design from our collection of examples by defining the key insight your chart should provide, and determining the focus elements. Finally, optimize your chart's design to direct attention to the most important information.

## Understand the chart types

Chart types refer to the broad categories of visual representations used to display data.  Each chart type is best-suited for particular kinds of data analysis or insights. Charts help users understand and interpret data by leveraging simplified visual representations that highlight patterns and relationships.<br/><br/>

  
    <FixedImage width="auto" height="128px" img src={`https://design.visa.com/assets/data-visualization/design-guidelines/selecting-a-chart/bar-chart.svg`} alt="Bar chart type"/>
  
  
    <FixedImage width="auto" height="128px" img src={`https://design.visa.com/assets/data-visualization/design-guidelines/selecting-a-chart/line-chart.svg`} alt="Line chart chart type"/>
  
  
    <FixedImage width="auto" height="128px" img src={`https://design.visa.com/assets/data-visualization/design-guidelines/selecting-a-chart/heatmap.svg`} alt="Heatmap chart type"/>
  
  
    <FixedImage width="auto" height="128px" img src={`https://design.visa.com/assets/data-visualization/design-guidelines/selecting-a-chart/scatterplot.svg`} alt="Scatterplot chart type"/>
  

<br/>

To learn more about each chart type visit the [Charts](https://design.visa.com/data-visualization/charts/overview)<!-- aria-label="Charts component library" --> guidelines.<br/><br/>
**Note:** Our guidelines currently only include these charts: Bar chart, dumbbell plot, line chart, and heatmap. You can explore our full library of chart components in the latest release of [Visa Chart Components (VCC)](https://github.com/visa/visa-chart-components)<!-- aria-label="Visa Chart Components (internal only) library" -->.

## Selecting a chart
Each chart type in our library includes specific examples which are adaptations created to solve real-world business problems. These work like templates or starter chart designs that include modifications that tailor the chart for specific data analysis tasks, or to emphasize particular aspects of the data.<br/><br/>
Use the insight and focus categories on our [Examples index](https://design.visa.com/data-visualization/charts/overview/examples)<!-- aria-label="Chart component library examples index" --> page to select a chart variation that is best suited for your user’s analysis needs.

<FeatureWithIcon icon={VisaIdeaHigh} style={{marginBlockEnd: '0'}}>
  <Typography variant="headline-4">Insights</Typography>
  <Typography variant="body-2">What do you want your audience to learn from this chart?</Typography>
</FeatureWithIcon>

<FeatureWithIcon icon={VisaSearchHigh} style={{marginBlockEnd: '0'}}>
  <Typography variant="headline-4">Focus</Typography>
  <Typography variant="body-2">What is the most important and meaningful information for users to focus on in this chart?</Typography>
</FeatureWithIcon>

### Step 1: Choose a key insight category
Insights refer to the high-level purpose of a chart, and the type of analysis it enables. Start by identifying the primary insight category of the chart, based on the type of question that it should enable users to answer. 

Table for understanding key insights and business questions

- Insight: How are items related?

- Insight: What is the current value of a metric, and is it good or bad?

- Insight: Which categories have a higher share of the whole?

- Insight: Is there a meaningful pattern between two numbers?

- Insight: How much difference is there between two numbers?

- Insight: What is the range of values, and how does it compare to the average?

- Insight: How do items move through a sequence?

- Insight: How has a number changed over time?

- Insight: Which items have the highest and lowest values?

- Insight: How does location impact a pattern?

### Step 2: Determine the focus

After you’ve selected an insight category, narrow down the examples by determining the key focus element of the chart. Focus elements refer to the specific data points, trends, patterns, or areas in a chart that are emphasized to make it easier for users to understand the key insights from the data.<br/><br/>
Three key focus areas that can be highlighted or emphasized: A specific category, within a dataset, and values relative to a threshold. The sections below illustrate how our chart examples have been customized to emphasize different focus elements.

### Highlight a category

Direct the user's focus to a primary category, as illustrated in the [Category share of total](https://design.visa.com/data-visualization/charts/heatmap/examples#heatmap-category-share-of-total)<!-- aria-label="Category share of total heatmap chart example" --> heatmap example.

<img src="https://design.visa.com/assets/data-visualization/design-guidelines/selecting-a-chart/category-share-of-total.svg" 
  alt="A heatmap comparing a percentage of resolved requests against a target percentage"
  class="chart-usage-img-margin-block-end-0"
/>

### Highlight values above a threshold

Direct the user's focus to values above a specific threshold, as illustrated in the [Compare trend to benchmark](https://design.visa.com/data-visualization/charts/bar-chart/examples#bar-chart-compare-trend-to-benchmark)<!-- aria-label="Compare trend to benchmark bar chart example" --> bar chart example.

<img src="https://design.visa.com/assets/data-visualization/design-guidelines/selecting-a-chart/compare-trend-to-benchmark.svg" 
  alt="A bar chart comparing monthly transactions across a 6 month span against a benchmark"
  class="chart-usage-img-margin-block-end-0"
/>

### Highlight high and low values

Direct the user's focus to the highest and lowest values, as illustrated in the [Trend with categories](https://design.visa.com/data-visualization/charts/dumbbell-plot/examples#dumbbell-plot-trend-with-categories)<!-- aria-label="Trend with categories dumbbell plot example" --> dumbbell plot example.

<img src="https://design.visa.com/assets/data-visualization/design-guidelines/selecting-a-chart/trend-with-categories.svg"  alt="A dumbbell plot comparing trends between two competitors across 12 months" class="chart-usage-img-margin-block-end-0" />

### Step 3: Refine the chart

Once you’ve chosen a chart example that works well for your use case, you can refine it to ensure it’s tailored to your audience’s needs. Use the following guidelines to help reduce distracting information and draw attention to the key elements of the chart.

### Reduce distracting information
To establish a clear visual focus, determine what elements only provide details or supporting information. This includes chart elements like gridlines, axes or axis elements, and data labels.  
- Create a clear visual focus by limiting distracting information and only adding visual details as need.
- Avoid using chart elements that convey similar or repeated information to help limit visual noise.
- Start by using one neutral color for all data points. This gives you a more flexible starting point for directing attention where it’s needed. 
- Use color encoding to provide additional information and context, where necessary. Follow guidelines for [Color palettes (internal only)](https://bookmarks.visa.com/vpds-neutral-data-visualization-color-palette)<!-- aria-label="Visa color palettes guidelines (internal only)" --> to make full use of our data visualization color palettes. 

### Direct attention
Once you have a simplified chart by reducing distracting elements, you can reintroduce visual emphasis to help users focus on the most important information in your chart.<br/><br/>
To direct attention to the right part of the chart, consider the user’s key task: What mental steps do they need to take to answer the key question? Determining the task type can help you choose what information to emphasize. 

Table for understanding task types and ways to direct attention

- Task type: Understand the precise value of a selected data point
- Description: - Use direct labeling of data points.
- Provide option to view the chart’s data in table format.

- Task type: Find a specific item or category within a chart
- Description: - Use color to represent individual categories, or to highlight the most important category.
- Provide interactive functionality to enable searching and highlighting specific data points.

- Task type: Find a pattern or an outlier
- Description: - Use reference lines to identify values above or below a threshold.
- Highlight outliers with different color or shape.
- Use annotations to identify and describe significant patterns.

- Task type: Compare the differences and similarities between two items, categories, or metrics
- Description: - Add reference lines to enable comparisons to the typical value.
- Use side-by-side positioning of multiple charts.
- Use statistical techniques for normalizing the data to enable more accurate comparisons.

<br/>
For more information about visual analysis tasks, reference the Data Representation Pillar of our [Data Experience Critique Framework](https://developer.visa.com/images2/visa-chart-components/Data%20Experience%20Critique%20Framework.pdf)<!-- aria-label="Data Experience Critique Framework" -->

---

# index

---
title: Start developing data visualizations
description: Select your code library and follow the step-by-step guide to start developing with Visa Chart Components.
tab_title: Angular
meta_description: Follow the step-by-step guide to start developing with Visa Chart Components in Angular.
side_nav_title: Development setup
tab_order: 0
side_nav_order: 1
---

import {
    installation,
    types,
    utils,
    compilerOptions,
    componentImport,
    componentTSFile,
    componentHTMLFile
} from "@data/angular/vcc/installation.ts";

## Step 1: Update Angular

Visa Chart Components (VCC) Angular library supports Angular v16 and up. Visit Angular's guide on how to [update Angular to v16](https://angular.io/guide/update-to-version-16) or [update Angular to v17](https://angular.io/guide/update-to-version-17).

## Step 2: Install the library

You can install the Visa Chart Components (VCC) Angular library using the package manager of your choice. Below we've provided the most common: NPM, PNPM, Yarn, and Bun.<br/><br/>

**Note:** Package managers can resolve dependencies differently and might not automatically install all required dependencies.

<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
    <CodeSnippetTabs exampleName='angular-data-viz-installation'  client:only="react" tabsList={['NPM', 'PNPM', 'Yarn', 'Bun']} code={installation} language="typescript">
    </CodeSnippetTabs>
</Utility>

### Step 2b: Install the types library

Next, install the accompanying types library to aid autocomplete features in IDEs and overall code quality.

<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
    <CodeSnippetTabs exampleName='angular-data-viz-types-installation' client:only="react" tabsList={['NPM', 'PNPM', 'Yarn', 'Bun']} code={types} language="typescript">
    </CodeSnippetTabs>
</Utility>

### Step 2c: Install the utilities library (optional)

Complete this step if you want to access optional functionalities of the Visa Chart Components, like internationalization.

<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
    <CodeSnippetTabs exampleName='angular-data-viz-utilities-installation' client:only="react" tabsList={['NPM', 'PNPM', 'Yarn', 'Bun']} code={utils} language="typescript">
    </CodeSnippetTabs>
</Utility>

## Step 3: Set up the application

### Step 3b: Update compilerOptions

Add paths in your tsconfig.

<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
    <CodeSnippetTabs exampleName='angular-data-viz-compiler-options' client:only="react" tabsList={['Angular 16', 'Angular 17' ]} code={compilerOptions} language="JSON">
    </CodeSnippetTabs>
</Utility>

### Step 3c: Import the Visa Chart Components (VCC) Angular library

Next, import the Visa Chart Components (VCC) Angular library for full access to our chart components. 

<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
    <CodeSnippet isStandalone={true} exampleName='angular-data-viz-angular-installation' client:only="react" code={componentImport} language="typescript">
    </CodeSnippet>
</Utility>

## Step 4: Use the components

### Step 4b: Update your components.ts

Update your components type script file to incorporate the minimal example props and data.

<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
    <CodeSnippet isStandalone={true} exampleName='angular-data-viz-component-update' client:only="react" code={componentTSFile} language="typescript">
    </CodeSnippet>
</Utility>

### Step 4c: Use the chart components

You're ready to use Angular chart components by copying and pasting the example code into your application. Check out [Bar chart](https://design.visa.com/data-visualization/charts/bar-chart/code)<!-- aria-label="Bar chart code tab" --> to give it a try. 

<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
    <CodeSnippet isStandalone={true} exampleName='angular-data-viz-component-usage' client:only="react" code={componentHTMLFile} language="typescript">
    </CodeSnippet>
</Utility>

## Need help?

If you experience any issues while getting set up with Visa Charts Components, visit [Support](https://design.visa.com/support)<!-- aria-label="Support" -->.


---

# react

---
title: Start developing data visualizations
description: Select your code library and follow the step-by-step guide to start developing with Visa Chart Components.
meta_description: Follow the step-by-step guide to start developing with Visa Chart Components in React.
side_nav_title: React
tab_order: 1
---

import { 
    installation,
    types,
    utils,
    component
} from "@data/react/vcc/installation.ts";

## Step 1: Update React

Visa Chart Components (VCC) React library supports React 18 and up. Visit React's guide on how to upgrade to [React 18](https://react.dev/blog/2022/03/08/react-18-upgrade-guide)<!-- aria-label="Update React to v18 (opens in a new tab)" --> for more. 

## Step 2: Install the library

You can install the Visa Chart Components (VCC) React library using the package manager of your choice. Below we've provided the most common: NPM, PNPM, Yarn, and Bun.<br/><br/>
**Note:** Package managers can resolve dependencies differently and might not automatically install all required dependencies.

<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
    <CodeSnippetTabs exampleName='react-data-viz-installation' client:only="react" tabsList={['NPM', 'PNPM', 'Yarn', 'Bun']} code={installation} language="typescript">
    </CodeSnippetTabs>
</Utility>

### Step 2b: Install the types library (optional)

Next, install the accompanying types library to aid autocomplete features in IDEs and overall code quality.

<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
    <CodeSnippetTabs exampleName='react-data-viz-types-installation' client:only="react" tabsList={['NPM', 'PNPM', 'Yarn', 'Bun']} code={types} language="typescript">
    </CodeSnippetTabs>
</Utility>

### Step 2c: Install the utilities library (optional)

Complete this step if you want to access optional functionalities of the Visa Chart Components, like internationalization.

<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
    <CodeSnippetTabs exampleName='react-data-viz-utilities-installation' client:only="react" tabsList={['NPM', 'PNPM', 'Yarn', 'Bun']} code={utils} language="typescript">
    </CodeSnippetTabs>
</Utility>

## Step 3: Use the chart components

You're ready to use React chart components by copying and pasting the example code into your application. Check out [Bar chart](https://design.visa.com/data-visualization/charts/bar-chart/code)<!-- aria-label="Bar chart code tab" --> to give it a try. 

<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
    <CodeSnippet isStandalone={true} exampleName='react-data-viz-usage' client:only="react" code={component} language="typescript">
    </CodeSnippet>
</Utility>

## Need help?

If you experience any issues while getting set up with Visa Charts Components, visit [Support](https://design.visa.com/support)<!-- aria-label="Support" -->.



---

# vanilla-javascript

---
title: Start developing data visualizations
description: Select your code library and follow the step-by-step guide to start developing with Visa Chart Components.
meta_description: Follow the step-by-step guide to start developing with Visa Chart Components in Vanilla JavaScript.
tab_title: Vanilla Javascript
tab_order: 2
---

import { 
    installation,
    utils,
    importOptions,
    propAssignment,
    propsObjectExample,
    components,
    html
} from "@data/js/vcc/installation.ts";

## Step 1: Install the library

You can install the Visa Chart Components (VCC) Web Components library using the package manager of your choice. Below we’ve provided the most common: NPM, PNPM, Yarn, and Bun.<br/><br/>
**Note:** Package managers can resolve dependencies differently and might not automatically install all required dependencies.

<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
    <CodeSnippetTabs exampleName='js-data-viz-installation' client:only="react" tabsList={['NPM', 'PNPM', 'Yarn', 'Bun']} code={installation} language="typescript">
    </CodeSnippetTabs>
</Utility>

### Step 1b: Install the types library (optional)

Next, install the accompanying types library to aid autocomplete features in IDEs and overall code quality.

<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
    <CodeSnippetTabs exampleName='js-data-viz-types-installation' client:only="react" tabsList={['NPM', 'PNPM', 'Yarn', 'Bun']} code={utils} language="typescript">
    </CodeSnippetTabs>
</Utility>

### Step 1c: Install the utilities library (optional)

Complete this step if you want to access optional functionalities of the Visa Chart Components, like internationalization.

<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
    <CodeSnippetTabs exampleName='js-data-viz-utilities-installation' client:only="react" tabsList={['NPM', 'PNPM', 'Yarn', 'Bun']} code={utils} language="typescript">
    </CodeSnippetTabs>
</Utility>

## Step 2: Set up the application

### Step 2b: Import the package

Import the package to access charts provided by Visa Chart Components.

<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
    <CodeSnippetTabs  exampleName='js-data-viz-packages-installation'client:only="react" tabsList={['index.html', 'ES Modules']} code={importOptions} language="typescript">
    </CodeSnippetTabs>
</Utility>

### Step 2c: Dynamic prop assignment (optional)

Build a function for dynamic prop assignment to dynamically update object properties.

<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
    <CodeSnippet isStandalone={true} exampleName='js-data-viz-types-dynamic-props' client:only="react" code={propAssignment} language="typescript">
    </CodeSnippet>
</Utility>

#### Example props object

<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
    <CodeSnippet isStandalone={true} exampleName='js-data-viz-example-props' client:only="react" code={propsObjectExample} language="typescript">
    </CodeSnippet>
</Utility>

## Step 3: Use the chart components

We support Vanilla components, the Template method, and the Jquery method. Choose the one that suit your needs.

### Step 3b: Declare a chart component

Declare any component to test a chart.

<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
    <CodeSnippetTabs exampleName='js-data-viz-declare-component' client:only="react" tabsList={['Vanilla Component', "Template Method", "jQuery Method"]} code={components} language="typescript">
    </CodeSnippetTabs>
</Utility>

### Step 3c: Use the chart components

You're ready to use the chart components by copying and pasting the example code into your application. Check out [Line chart](https://design.visa.com/data-visualization/charts/line-chart/examples)<!-- aria-label="Line chart examples" --> to give it a try. 

<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
    <CodeSnippet isStandalone={true} exampleName='react-data-viz-usage' client:only="react" code={html} language="typescript">
    </CodeSnippet>
</Utility>

 ## Need help?

If you experience any issues while getting set up with Visa Charts Components, visit [Support](https://design.visa.com/support)<!-- aria-label="Support" -->.



---

# index

---
title: Visa Chart Components
tab_title: Visa Chart Components
description: Learn how to use Visa Chart Components with the Visa Product Design System for ease and efficiency.
meta_description: Learn how to use Visa Chart Components with the Visa Product Design System for ease and efficiency.
page_size: medium
side_nav_title: Visa Chart Components
side_nav_order: 0
show_table_of_contents: false
---

The Visa Chart Components library (VCC) is maintained to provide charts that work alongside VPDS’s component libraries. You’ll also find guidelines including general principles on how to craft informative data experiences and how to select effective charts.

## Learn about VCC

Visa Chart Components uses a feature-rich API to bring you accessible, framework-agnostic web components with robust accessibility configurations to enhance your workflow and ensure your product meet the latest standards. Learn about our approach below. 

<br /><br />

<FeatureWithIcon customWidth='50' customHeight='50' icon={VisaAccessibilityHigh}>
  ### Accessibility first
  <Typography variant="body-2">Visa Chart Components are designed to make it easier for product teams to deliver accessible data experiences. We use Visa Global Accessibility Requirements (VGAR) to continuously assess and improve the accessibility of our data components.</Typography>
</FeatureWithIcon>

<FeatureWithIcon icon={VisaSpecsHigh}>
  ### Streamlined design
  <Typography variant="body-2">Our component APIs come with built-in design choices tailored for Visa products, reducing the need for developers to code detailed aspects like motion design into each chart. This intentional design choice may offer less flexibility than some other libraries, as VCC is not a low-level library.</Typography>
</FeatureWithIcon>

<FeatureWithIcon icon={VisaConnectHigh}>
  ### Framework agnostic
  <Typography variant="body-2">Visa Chart Components leverage [stencil.js](https://stenciljs.com/), [d3.js](https://d3js.org/), and other open-source libraries to build custom web components that work with popular web frameworks like Angular, React, and Vanilla JavaScript. In short, you can use VCC almost anywhere you use JavaScript. At this time, the team doesn’t support mobile chart components yet, but can offer guidance on adjusting for mobile applications.</Typography>
</FeatureWithIcon>

<FeatureWithIcon icon={VisaCheckedMultipleHigh}>
  ### Unit tested
  <Typography variant="body-2">We've developed detailed, semi-automated unit testing to perform robust regression testing, ensuring consistent quality across our components. This helps ensure we’re continuously improving the breadth and depth of our testing coverage.</Typography>
</FeatureWithIcon>

## Learn to use our assets

Craft insightful, inclusive, and accessible data experiences following our data visualization guidelines.
- Understand key principles and techniques for visualizing and communicating insights in [Data visualization principles.](https://design.visa.com/data-visualization/design-visualization-guidelines/data-visualization-principles)<!-- aria-label="Data visualization principles" -->
- Explore how to choose the most effective chart for the information you need to communicate in [Selecting the right chart.](https://design.visa.com/data-visualization/design-visualization-guidelines/selecting-a-chart)<!-- aria-label="Chart selection" -->
- Find usage, code and accessibility guidance for our data visualization components in [Chart component library.](https://design.visa.com/data-visualization/charts/overview)<!-- aria-label="Chart component library" -->
- Find chart examples tailored to support common business scenarios and analysis tasks in [Chart examples.](https://design.visa.com/data-visualization/charts/overview/examples)<!-- aria-label="Chart examples" -->

## Complete your setup

To get started, visit [React](https://design.visa.com/data-visualization/development-setup/react)<!-- aria-label="React" -->, [Angular](https://design.visa.com/data-visualization/development-setup)<!-- aria-label="Angular" -->, and [Vanilla Javascript](https://design.visa.com/data-visualization/development-setup/vanilla-javascript)<!-- aria-label="Vanilla Javascript" --> for instructions on installation and building your first chart.

### For designers: Get the Figma design kit

Start designing with VCC components, color palettes, and more with our [Figma Data Visualization library (internal only)](https://bookmarks.visa.com/vpds-figma-data-visualization-library).

### For developers: Install the code library of your choice

Visa Chart Components can be used with React, Angular, Vanilla JavaScript, Python, and Vue. To get started, visit [Angular](https://design.visa.com/data-visualization/development-setup)<!-- aria-label="Angular" -->, [React](https://design.visa.com/data-visualization/development-setup/react)<!-- aria-label="React" -->, and [Vanilla Javascript](https://design.visa.com/data-visualization/development-setup/vanilla-javascript)<!-- aria-label="Vanilla Javascript" --> for instructions on installation and building your first chart.

## Connect with us

Have questions or ideas? Visit our office hours, or join Data experience on Teams or get general VPDS help by visiting [Support](https://design.visa.com/support)<!-- aria-label="Support" -->.

---

# bar-chart-compare-category-ranking

---
title: Compare category ranking
shortTitle: Compare category ranking
description: Bar chart used to compare differences between categories, such as countries or product types.
thumbnail: assets/data-visualization/examples/bar/compare-category-ranking.svg
filter: 
    type: bar
    insight: 
        - ranking
example:
    id: bar-chart-compare-category-ranking
    chartTag: bar-chart
    hasCousinNavigation: true
---

<ChartExampleHeader 
    id={frontmatter.example.id}
    title={frontmatter.title} 
    filter={frontmatter.filter}
/>

In this example, the chart is optimized to answer the key business question, “Which countries performed better?”, and “What are the similarities and differences between regions?”. The following elements help emphasize the key takeaways: 
- **Color palette:** Use the categorical palette to group bars into relevant groups. In this example, this helps indicate which regions had countries that ranked towards the top or the bottom and compare countries within a region.
- **Data labels:** Show lables directly over each bar to make it easier to interpret the exact value of each data point. 
- **Reference line:** Use the reference line to provide a reference point between each country and the average value.
- **Order:** Order countries from highest to lowest to make it easy to identify the ranking of countries at a quick glance.

<ChartExample 
    client:only="react"
    exampleProps={{
        id: 'bar-chart-compare-category-ranking',
        titleColor: '#4A4A4A',
        filter: frontmatter.filter,
        chartTag: frontmatter.example.chartTag,
        hasCousinNavigation: frontmatter.example.hasCousinNavigation
    }} 
/>

---

# bar-chart-compare-trend-to-benchmark

---
title: Compare trend to benchmark
shortTitle: Compare trend to benchmark
description: Bar chart used to compare trends to a threshold such as goal, budget or average.
thumbnail: assets/data-visualization/examples/bar/trend-to-benchmark.svg
filter: 
    type: bar
    insight: 
        - trend
    focus: 
        - values relative to threshold
example:
    id: bar-chart-compare-trend-to-benchmark
    chartTag: bar-chart
    hasCousinNavigation: false
---

<ChartExampleHeader 
    id={frontmatter.example.id}
    title={frontmatter.title} 
    filter={frontmatter.filter}
/>

In this example, the chart is optimized to answer the key business question, “How did performance change over time?” and “When did our performance beat the market average?”. The following elements help emphasize the key takeaways: 
- **Color palette:** Use a combination of bold and subtle colors to emphasize which bars fall above or below the benchmark. This example uses the gray and blue highlight palette.
- **Data labels:** Show lables at the bottom of each bar to make it easier to interpret the exact value of each data point without overcrowding the benchmark line.
- **Reference line:** Use the reference line to help users understand which values are good, bad, or typical.

<ChartExample 
    client:only="react" 
    exampleProps={{
        id: 'bar-chart-compare-trend-to-benchmark',
        titleColor: '#4A4A4A',
        filter: frontmatter.filter,
        chartTag: frontmatter.example.chartTag,
        hasCousinNavigation: frontmatter.example.hasCousinNavigation
    }} 
/>

---

# bar-chart-distribution-summary

---
title: Distribution summary
description: Bar chart used to summarize the range of values of a distribution and identify the most common values.
thumbnail: assets/data-visualization/examples/bar/distribution-summary.svg
filter: 
    type: bar
    insight: 
        - distribution
example:
    id: bar-chart-distribution-summary
    chartTag: bar-chart
    hasCousinNavigation: false
---

<ChartExampleHeader 
    id={frontmatter.example.id}
    title={frontmatter.title} 
    filter={frontmatter.filter}
/>

In this example, the chart is optimized to answer the key business question, “What is the range of values of low to high spenders?” and “What are the most common values, and how do they compare to the average?”. The following elements help emphasize the key takeaways: 
- **Color palette:** Use sequential colors to emphasize the value of bars, typically with darker bars indicating larger values. This example uses the purple sequential color palette.
- **Annotations:** Include annotations to provide a summary of the important data points and in-context instructions to help users interpret the chart.
- **Center baseline axis:** Use a centered baseline on the Y axis to keep the focus on the overall shape of the distribution.

<ChartExample 
    client:only="react" 
    exampleProps={{
        id: 'bar-chart-distribution-summary',
        titleColor: '#4A4A4A',
        filter: frontmatter.filter,
        chartTag: frontmatter.example.chartTag,
        hasCousinNavigation: frontmatter.example.hasCousinNavigation
    }} 
/>

---

# bar-chart-simple-trend

---
title: Simple trend
description: Bar chart used to summarize and compare trends.
thumbnail: assets/data-visualization/examples/bar/simple-trend.svg
filter: 
    type: bar
    insight: 
        - trend
example:
    id: bar-chart-simple-trend
    chartTag: bar-chart
    hasCousinNavigation: false
---

<ChartExampleHeader 
    id={frontmatter.example.id}
    title={frontmatter.title} 
    filter={frontmatter.filter}
/>

In this example, the chart is optimized to answer the key business question, “How did performance change over time?”. The following elements help emphasize the key takeaways:
- **Color palette:** Use one color for every bar to emphasize the overall shape of the trend without overwhelming users. This example uses the neutral blue from our single color palette.
- **Data labels:** Show labels directly over each bar to make it easier to interpret the exact value of each data point.
- **Gridlines:** Use horizontal gridlines to make it easier to compare heights between non-adjacent bars.

<ChartExample 
    client:only="react" 
    exampleProps={{
        id: frontmatter.example.id,
        filter: frontmatter.filter,
        titleColor: "#1434cb",
        chartTag: frontmatter.example.chartTag,
        endpoint: frontmatter.example.endpoint,
        hasCousinNavigation: frontmatter.example.hasCousinNavigation
    }} 
/>


---

# bar-chart-trend

---
title: Trend
description: Bar chart used to identify high and low values and comparing trends.
thumbnail: assets/data-visualization/examples/bar/trend.svg
filter: 
    type: bar
    insight: 
        - trend
    focus: 
        - high and low values
example:
    id: bar-chart-trend
    chartTag: bar-chart
    hasCousinNavigation: true
---

<ChartExampleHeader 
    id={frontmatter.example.id}
    title={frontmatter.title} 
    filter={frontmatter.filter}
/>

In this example, the chart is optimized to answer the key business question, “How did performance change over time?”. The following elements help emphasize the key takeaways: 
- **Color palette:** Use sequential colors with a legend to categorize bars according to their values and make it easier to spot the high and low values. This example uses the secondary blue sequential color palette.
- **Data labels:** Show lables directly over each bar to make it easier to interpret the exact value of each data point.
- **Gridlines:** Use horizontal gridlines to make it easier to compare heights between non-adjacent bars.

<ChartExample 
    client:only="react" 
    exampleProps={{
        id: frontmatter.example.id,
        titleColor: "#1434cb",
        noCodePreview: false,
        chartTag: frontmatter.example.chartTag,
        hasCousinNavigation: frontmatter.example.hasCousinNavigation
    }} 
/>



---

# dumbbell-plot-compare-trend-to-benchmark

---
title: Compare trend to benchmark
shortTitle: Compare trend to benchmark
description: Dumbbell plot used to identify over or underperforming categories relative to a benchmark.
thumbnail: assets/data-visualization/examples/dumbbell/compare-trend-to-benchmark.png
filter: 
    type: dumbbell
    insight: 
        - deviation
    focus: 
        - values relative to threshold
example:
    id: dumbbell-plot-compare-trend-to-benchmark
    chartTag: dumbbell-plot
---

<ChartExampleHeader 
    id={frontmatter.example.id}
    title={frontmatter.title} 
    filter={frontmatter.filter}
/>

In this example, the chart is optimized to answer the key business question: “Which cities performed above or below average?”. The following elements help emphasize the key takeaways: 
- **Color palette:** Use two colors to highlight important data on the chart. In this example, the gray and red highlight color palette emphasizes cities that performed below average.
- **Data labels:** Directly label each point to make it easier to interpret the exact value. This example provides additional labels with the difference from the benchmark for quicker analysis. 
- **Reference line:** Include a reference line to indicate the benchmark for comparing which values are good or bad. In this example, it shows the the overall U.S. average.
- **Axis annotation:** Use annotations to give contextual explanations of the data. In this example, the annotation labels and arrows at the top of the chart explain how to interpret values along the horizontal axis, as well as how to interpret the red and gray colors.

<ChartExample 
    client:only="react" 
    exampleProps={{
        id: frontmatter.example.id,
        titleColor: '#4A4A4A',
        filter: frontmatter.filter,
        chartTag: frontmatter.example.chartTag,
    }} 
/>

---

# dumbbell-plot-current-vs-previous-trend

---
title: Current vs previous trend
shortTitle: Current vs previous trend
description: Dumbbell plot used to compare variance and pace of growth between two date periods.
thumbnail: assets/data-visualization/examples/dumbbell/compare-current-vs-previous-trend.png
filter: 
    type: dumbbell
    insight: 
        - deviation
        - trend
    focus: 
        - highlight category
example:
    id: dumbbell-plot-current-vs-previous-trend
    chartTag: dumbbell-plot
---

<ChartExampleHeader 
    id={frontmatter.example.id}
    title={frontmatter.title} 
    filter={frontmatter.filter}
/>

In this example, the chart is optimized to answer the key business questions: “Did this year’s performance beat last year’s and by how much?” and “Is that difference growing or shrinking?”. The following elements help emphasize the key takeaways: 
- **Color palette:** Use two colors to highlight important data on the chart. In this example, the gray and blue highlight color palette emphasizes the direction of the change from last year. 
- **Data labels:** Label important data points to help users interpret the data in the chart without overcrowding the display. In this example, labeling the minimum point, maximum point, and most recent data gives the overall range of the data.
- **Gridlines:** Use vertical gridlines to help users understand which month each dumbbell corresponds to. 
- **Marker type:** Use the arrow marker type to emphasize the direction of change, making it easier to quickly understand if this year’s performance was an increase or decrease from last year. 

<ChartExample 
    client:only="react"
    exampleProps={{
        id: frontmatter.example.id,
        titleColor: '#4A4A4A',
        filter: frontmatter.filter,
        chartTag: frontmatter.example.chartTag,
    }} 
/>

---

# dumbbell-plot-trend-with-categories

---
title: Trend with categories
description: Dumbbell plot used to compare variance between two categories over time.
thumbnail: assets/data-visualization/examples/dumbbell/trend-with-categories.png
filter: 
    type: dumbbell
    insight: 
        - deviation
        - trend
    focus: 
        - high and low values
example:
    id: dumbbell-plot-trend-with-categories
    chartTag: dumbbell-plot
    hasCousinNavigation: false
---

<ChartExampleHeader 
    id={frontmatter.example.id}
    title={frontmatter.title} 
    filter={frontmatter.filter}
/>

In this example, the chart is optimized to answer the key business questions: “When did our customer growth outpace competitors?”, “How much difference is there between our rate of customer growth and competitors?”, and “How did customer growth change over time?”. The following elements help emphasize the key takeaways: 
- **Color palette:** Use two colors to indicate the series membership of each dot. This example uses the gray and blue highlight color palette to emphasize months where the selected client’s performance was better than the competitor benchmark, where the bar is colored based on which series has the highest value. 
- **Data labels:** Label important data points to help users interpret the data in the chart without overcrowding the display. In this example, labeling the minimum point, maximum point, and most recent data gives the overall range of the data.
- **Gridlines:** Use vertical gridlines to help users understand which month each dumbbell corresponds to. 

<ChartExample 
    client:only="react" 
    exampleProps={{
        id: frontmatter.example.id,
        filter: frontmatter.filter,
        titleColor: "#1434cb",
        chartTag: frontmatter.example.chartTag,
        hasCousinNavigation: false
    }} 
/>


---

# heatmap-category-pattern-analysis

---
title: Category pattern analysis
description: Heatmap used to compare categories across discrete date parts.
thumbnail: assets/data-visualization/examples/heatmap/category-pattern-analysis.png
filter: 
    type: heatmap
    insight: 
        - correlation
        - trend
    focus: 
        - high and low values
example:
    id: heatmap-category-pattern-analysis
    chartTag: heatmap
---

<ChartExampleHeader 
    id={frontmatter.example.id}
    title={frontmatter.title} 
    filter={frontmatter.filter}
/>

In this example, the chart is optimized to answer the key business questions: ”Do customers prefer to shop on weekdays or weekends, or on a specific day of the week?” and “Which key market segments have similar or different customer purchase patterns?”. The following elements help emphasize the key takeaways: 
- **Color palette:**  Use color encoding to make very large and very small numbers easier to spot. In this example, this heatmap uses a the full range of colors in the sequential blue palette, with darker colors representing higher quantities.
- **Data labels:** Label every data marker to make it easier to interpret the exact value of each data point.
- **Grouping categorical variable:** Combine smaller groups into one category called “other” to help users focus on the largest categories.
- **Grouping time variable:**  Group exact dates into segments, like days of the week or times of day, to help users identify recurring seasonal patterns.
- **Legend:** Use a gradient color legend to help users focus on overall patterns or clusters of high and low values, instead of attempting to use color to interpret precise values of individual cells.

<ChartExample 
    client:only="react"
    exampleProps={{
        id: frontmatter.example.id,
        filter: frontmatter.filter,
        titleColor: "#1434cb",
        chartTag: frontmatter.example.chartTag,
    }} 
/>

---

# heatmap-category-share-of-total

---
title: Category share of total
description: Heatmap used to highlight one category's contribution to the total, and compare values to a threshold.
thumbnail: assets/data-visualization/examples/heatmap/category-share-of-total.png
filter: 
    type: heatmap
    insight: 
        - composition
        - current status
    focus: 
        - highlight category
example:
    id: heatmap-category-share-of-total
    chartTag: heatmap
    hasCousinNavigation: false
---

<ChartExampleHeader 
    id={frontmatter.example.id}
    title={frontmatter.title} 
    filter={frontmatter.filter}
/>
In this example, the chart is optimized to answer the key business questions: “What share of all requests have been completed?” and “How close did we get to our target for resolving requests?”. The following elements help emphasize the key takeaways: 
- **Color palette:** Use color to show highlight important data. In this example, the gray and blue palette highlights the resolved requests category compared to all requests.  
- **Subtitle:** Use subtitles to provide a clear and concise summary of the key takeaways from the chart.
- **Annotation:** Use annotations to emphasize the exact value of the highlighted category and make it easier to understand how to read the chart.
- **Reference line:** Provide a visual indicator of the set goal, making it easy to see the progress made and the distance remaining to achieve the goal.

<ChartExample 
    client:only="react"
    exampleProps={{
        id: frontmatter.example.id,
        filter: frontmatter.filter,
        titleColor: "#1434cb",
        chartTag: frontmatter.example.chartTag
    }} 
/>


---

# heatmap-correlation-matrix

---
title: Correlation matrix
description: Heatmap used to compare two metrics, and identify the most and least common combinations.
thumbnail: assets/data-visualization/examples/heatmap/correlation-matrix.png
filter: 
    type: heatmap
    insight: 
        - correlation
    focus: 
        - high and low values
example:
    id: heatmap-correlation-matrix
    chartTag: heatmap
---

<ChartExampleHeader 
    id={frontmatter.example.id}
    title={frontmatter.title} 
    filter={frontmatter.filter}
/>
In this example, the chart is optimized to answer the key business question: “Is there a meaningful relationship between how much a cardholder spends and how frequently they shop?”. The following elements help emphasize the key takeaways: 
- **Color palette:** Use color to highlight important patterns. In this example, the complementary blue palette makes the most common combinations of spend amount and purchase frequency easier to spot. 
- **Data labels:** Label every data marker to make it easier to interpret the exact value of each data point.
- **Grouping categorical variables:** Translate continuous numeric variable into a few clear categories (like small, medium, and large) to simplify comparisons.
- **Simplified number format:** Rounding data labels to whole percentage points to reduce the effort needed to compare values.

<ChartExample 
    client:only="react"
    exampleProps={{
        id: frontmatter.example.id,
        titleColor: '#4A4A4A',
        filter: frontmatter.filter,
        chartTag: frontmatter.example.chartTag
    }} 
/>


---

# heatmap-seasonal-pattern-analysis

---
title: Seasonal pattern analysis
description: Heatmap used to visualize a metric in a calendar format, to identify seasonal peak.
thumbnail: assets/data-visualization/examples/heatmap/seasonal-pattern-analysis.png
filter: 
    type: heatmap
    insight: 
        - correlation
        - trend
    focus: 
        - high and low values
example:
    id: heatmap-seasonal-pattern-analysis
    chartTag: heatmap
---

<ChartExampleHeader 
    id={frontmatter.example.id}
    title={frontmatter.title} 
    filter={frontmatter.filter}
/>
In this example, the chart is optimized to answer the key business questions: “Are there any seasonal patterns when there are peaks or dips in new accounts?” and “Have the slow and busy seasons remained steady, or do they change from year to year?”. The following elements help emphasize the key takeaways: 
- **Color palette:** Use color to make clusters with very large and very small numbers easier to spot. In this example, the plum color palette represents the total of new accounts for each month, with darker colors indicating higher quantities.
- **Data labels:**  Label every data marker to make it easier to interpret the exact value of each data point.
- **Legend:** Use a color legend to help users easily interpret the color encoding of heatmap cells. In this example, each heatmap cell is labeled with its corresponding month and the legend tells users how to interpret each cell’s color.

<ChartExample 
    client:only="react" 
    exampleProps={{
        id: frontmatter.example.id,
        titleColor: '#4A4A4A',
        filter: frontmatter.filter,
        chartTag: frontmatter.example.chartTag
    }} 
/>

---

# line-chart-compare-trend-to-benchmark

---
title: Compare trend to benchmark
shortTitle: Compare trend to benchmark
description: Line chart used to compare trends to a threshold such as goal, budget or average.
thumbnail: assets/data-visualization/examples/line-chart/compare-trend-to-benchmark.svg
filter: 
    type: line
    insight: 
        - trend
    focus:
        - values relative to threshold
example:
    id: line-chart-compare-trend-to-benchmark
    chartTag: line-chart
---

<ChartExampleHeader 
    id={frontmatter.example.id}
    title={frontmatter.title} 
    filter={frontmatter.filter}
/>

In this example, the chart is optimized to answer the key business questions, “How did expenses change over time?” and “When did expenses exceed budget?”. The following elements help emphasize the key takeaways:
- **Color palette:** Use bold and subtle colors to emphasize which data points fall above or below the benchmark. This example uses the gray and red color palette to emphasize months where expenses exceeded the budget.
- **Data labels:** Show labels directly over each data marker to make it easier to interpret the exact value of each data point.
- **Gridlines:** Show horizontal gridlines make it easier to compare differences across all data points.
- **Reference line:** Provide a comparison to the target budget threshold to help users understand which values are good or bad.

<ChartExample 
    client:only="react" 
    exampleProps={{
        id: frontmatter.example.id,
        titleColor: '#4A4A4A',
        filter: frontmatter.filter,
        chartTag: frontmatter.example.chartTag
    }} 
/>


---

# line-chart-current-versus-previous-trend

---
title: Current vs. previous trend
shortTitle: Current vs. previous trend
description: Line chart used to compare a primary metric to a secondary metric, such as current to previous year.
thumbnail: assets/data-visualization/examples/line-chart/current-vs-previous-trend.svg
filter: 
    type: line
    insight: 
        - trend
    focus: 
        - highlight category
example:
    id: line-chart-current-versus-previous-trend
    chartTag: line-chart
---

<ChartExampleHeader 
    id={frontmatter.example.id}
    title={frontmatter.title} 
    filter={frontmatter.filter}
/>

In this example, the chart is optimized to answer the key business questions, “How did performance change over time?” and “How much difference is there between this year and last year’s performance?”. The following elements help emphasize the key takeaways:
- **Color palette:** Use bold and subtle colors to emphasize the change in values over time. This example uses a gray and blue highlight color palette to emphasize the current year’s trend line.
- **Data labels:** Show labels directly over each data marker on the current year's line to make it easier to interpret the exact value of each data point, and help direct attention to the most recent data. This allows users to estimate the gap between current and previous year's data points without overcrowding the chart.
- **Stepped line style:** Use a stepped line chart to emphasize the exact value of each data point and the change between consecutive data points. In this example, the stepped line style helps users easily interpret small changes, and make more precise comparisons between two line series.
- **Y axis labels:** Use axis labels to help users estimate the value of unlabeled data points.

<ChartExample 
    client:only="react" 
    exampleProps={{
        id: frontmatter.example.id,
        filter: frontmatter.filter,
        titleColor: "#1434cb",
        chartTag: frontmatter.example.chartTag,
    }} 
/>

---

# line-chart-one-versus-all-trend

---
title: One vs. all trend
shortTitle: One vs. all trend
description: Line chart used to compare differences in trends between multiple categories, with emphasis on a primary category.
thumbnail: assets/data-visualization/examples/line-chart/one-vs-all.svg
filter: 
    type: line
    insight: 
        - trend
    focus: 
        - highlight category
example:
    id: line-chart-one-versus-all-trend
    chartTag: line-chart
---

<ChartExampleHeader 
    id={frontmatter.example.id}
    title={frontmatter.title} 
    filter={frontmatter.filter}
/>

In this example, the chart is optimized to answer the key business question, “Which countries are experiencing faster or slower pace of growth?”. The following elements help emphasize the key takeaways:
- **Color palette:** Use bold and subtle colors to emphasize overall trend patterns. In this example, the gray and blue highlight color palette emphasizes the worldwide trend line.
- **Data abstraction:** Using the first date period (Q1 FY21) as a baseline allows for easier comparisons of relative growth across countries with diverse economic sizes.
- **Number formatting:** Use symbols and formatting to clarify the meaning. In this example, including a plus sign (+) in the axis labels helps clearly communicate growth rates.

<ChartExample 
    client:only="react"  
    exampleProps={{
        id: frontmatter.example.id,
        filter: frontmatter.filter,
        titleColor: "#1434cb",
        chartTag: frontmatter.example.chartTag
    }} 
/>

---

# line-chart-trend-with-categories

---
title: Trend with categories
description: Line chart used to compare differences in trends between two to five categories.
thumbnail: assets/data-visualization/examples/line-chart/trend-with-categories.svg
filter: 
    type: line
    insight: 
        - trend
example:
    id: line-chart-trend-with-categories
    chartTag: line-chart
---

<ChartExampleHeader 
    id={frontmatter.example.id}
    title={frontmatter.title} 
    filter={frontmatter.filter}
/>

In this example, the chart is optimized to answer the key business questions, “How did performance change over time?” and “Is the gap between the two categories growing or shrinking?”. The following elements help emphasize the key takeaways:
- **Color palette:** Use colors from the categorical color palette to ensure both categories have equal visual emphasis and importance.
- **Data labels:** Show labels directly over each data marker to make it easier to interpret the exact value of each data point.
- **Gridlines:** Show horizontal gridlines to make it easier to compare differences across all data points.

<ChartExample 
    client:only="react"
    exampleProps={{
        id: frontmatter.example.id,
        filter: frontmatter.filter,
        titleColor: "#1434cb",
        chartTag: frontmatter.example.chartTag
    }} 
/>

---

# index

---
title: Brand guidance for products
description: Discover essential guidelines for Visa products, including card art, fictitious brands and user aliases, as well as logo creation and naming conventions.
meta_description: Discover essential guidelines for Visa products, including card art, fictitious brands and user aliases, as well as logo creation and naming conventions.
page_size: full-width
side_nav_title: Brand guidance for products
side_nav_additional_screenreader_title: for the Brand guidance for products
side_nav_order: 0
show_table_of_contents: false
---

<LibraryCardListLarge>
    <LibraryCardLarge 
        title="Card art (internal only)" 
        description="Learn how to ensure Visa brand standards are met when representing digital cards."
        href={`https://bookmarks.visa.com/vpds-card-art`} 
        thumbnail={`https://design.visa.com/assets/designing/card-art/card-art.svg`}
        external
        aria-label={"Card art (internal only, opens in new tab)"}
        hoverColor={colorGreen}
    />
    <LibraryCardLarge 
        title="Fictitious brands and aliases (internal only)" 
        description="Find VPDS-approved fictitious brands and fake user aliases for use in demos and marketing materials."
        href={`https://bookmarks.visa.com/vpds-fictitious-brands`}  
        thumbnail={`https://design.visa.com/assets/designing/fictitious-brands/fictitious-brands-graphics.svg`}
        external
        aria-label={"Fictitious brands and aliases (internal only, opens in new tab)"}
        hoverColor={colorGreen}
    />
    <LibraryCardLarge 
        title="Logo and naming (internal only)" 
        description="Learn how to correctly use the Visa name and logo across Visa and non-Visa branded products."
        href={`https://bookmarks.visa.com/vpds-logo-and-naming`}
        thumbnail={`https://design.visa.com/assets/designing/logo-and-naming/logo-and-naming.svg`}
        external
        aria-label={"Logo and naming (internal only, opens in new tab)"}
        hoverColor={colorGreen}
    />
</LibraryCardListLarge>

---

# index

---
title: Design kits
description: Prototype quickly with VPDS design kits, equipped with everything you need to create user-friendly experiences.
meta_description: Prototype quickly with VPDS design kits, equipped with everything you need to create user-friendly experiences.
side_nav_order: -1
---

## Internal users

#### Step 1: Sign into Figma using Visa SSO

Visa employees should be added to our Figma organization automatically. Once signed in, there's no need to join or request to join any specific team to access the [Nova Figma libraries](https://www.figma.com/files/939645710326344313/team/979490301166271164/Nova?fuid=958800392878624560).

#### Step 2: Ensure VPDS libraries are enabled

In your design file, navigate to the left-side navigation panel and select **Libraries**. A modal will pop up.<br/><br/>

The **Nova: Components** and **Nova: Icons** libraries will be enabled automatically and indicated by a checkmark. Additional libraries such as **Data Experience: Charts** can also be enabled from this modal using the search field or by navigating to **Your organization** and then selecting the **Visa Product Design System (VPDS)**.

## External users

#### Step 1: Sign into Figma

Use your credentials to access the Figma platform. If you don't have an account, you can create one for free.

#### Step 2: Get the libraries

Navigate to the [Visa Product Design System](https://www.figma.com/@visa) within the Figma community. 

#### Step 3: Duplicate the file to your workspace
Explore the Visa Product Design System files and select one to duplicate in your own workspace.

## Start designing

#### Find and place components

The Visa Product Design System includes more than 50 components, patterns, and their variants. Navigate to or search for components from the **Assets** tab in the left-side navigation panel, and drag and drop them to the stage. Use the **Application layouts** to start your designs from preset examples.<br/><br/>

For more help on how to use Figma, visit [Figma Learn](https://help.figma.com/hc/en-us/categories/360002051613-Get-started)

#### Adjust component properties

Drag the component you wish to use onto canvas. The component will be selected, allowing you to view the name of the component in the right-side properties panel until deselected. If the component has variants, you’ll see fields underneath the component name to configure the properties and values of that component set.<br/><br/>

Need to customize a component beyond the properties provided in the panel? Find out more about theming and customization in [Design tokens for designers](https://design.visa.com/base-elements/design-tokens/tokens-for-designers).

#### Apply color and text styles
Visa Product Design System color and typography design tokens are surfaced in Figma using styles. As you design, you can use these styles to ensure consistency as you add your own elements. Access these styles in the right-side properties panel under **Appearance**.<br/><br/>
Learn more about using color, typography, and more in [Base elements](https://design.visa.com/base-elements/).<br/><br/>
For more help on how using variables in Figma, visit [Figma Learn](https://help.figma.com/hc/en-us/articles/15343816063383-Modes-for-variables)


---

# index

---
title: Start designing with VPDS
description: Learn how to start designing with the Visa Product Design System using this step-by-step guide for ease and efficiency.
meta_description: Learn how to start designing with the Visa Product Design System using this step-by-step guide for ease and efficiency.
side_nav_title: Get started
show_table_of_contents: false
---

## Step 1: Familiarize yourself with the system

Check out the Visa Product Design System documentation. It's filled with principles and best practices that will provide a solid foundation, even in the absence of a dedicated design or content team.

- Understand our foundational principles including [Accessibility](https://design.visa.com/global-accessibility-requirements) and [Inclusive design](https://design.visa.com/about-VPDS/inclusive-design) in About VPDS.
- Discover our system's visual and architectural standards used to ensure consistent digital experiences in [Base elements](https://design.visa.com/base-elements).
- Find usage, specs, and accessibility guidance for the building blocks of the system in [Components](https://design.visa.com/components).
- Find layouts for common tasks like uploading a file or requesting a one-time passcode in [Patterns](https://design.visa.com/patterns).
- Create insightful, inclusive, and accessible data experiences for everyone, everywhere with [Data visualization](https://design.visa.com/data-visualization).
- Discover all the essentials for writing product content like voice and tone, grammar, and alert messaging in [Content](https://design.visa.com/content).

## Step 2: Get the Figma design kits

The VPDS team maintains design kits in Figma. These include components and styles that are updated automatically with each system release. To get set up, visit [Design kits](https://design.visa.com/designing/design-kits) and follow the instructions for internal or external users.

## Step 3: Connect with us

Have questions or ideas? Subscribe to our email list, visit our office hours, or join us on Teams by visiting [Support](https://design.visa.com/support).

---

# index

---
title: Accessibility utilities
side_nav_additional_screenreader_title: for Angular
description: Create screen reader-friendly code in Angular to enhance the accessibility of your web apps.
---

<CodePage library={ANGULAR} />

---

# index

---
title: Changelog
side_nav_additional_screenreader_title: for Angular
description: Keep up-to-date with the latest updates and enhancements in the Angular changelog.
side_nav_order: 1
show_table_of_contents: false
---

<Banner>
    <MessageIcon />
    <BannerContent className="v-pl-2 v-pb-2">
    <p>
      Learn more about the latest Nova Angular version in our article, 
      [Meet Nova Angular 6](https://design.visa.com/what's-new/latest-news/fy25-nova-angular-6)<!-- aria-label="Meet Nova Angular 6" -->.
    </p>
    <p>
      For step-by-step instructions on upgrading from Nova Angular 5.x to 6.x, refer to the 
      [Migration guide](https://github.com/visa/nova-angular/blob/main/MIGRATION_GUIDE.md)<!-- aria-label="Migration guide" -->.
    </p>
    </BannerContent>
</Banner>

<br />

<Changelog client:only="react" library="angular"  >
  <SkeletonChangelog slot="fallback" />

  <Typography variant="headline-4" tag="h3">7.0.0 (2026-03-20)</Typography>
  <Typography variant="body-1" tag="p">
    This release adds Angular 21 support and drops Angular 18 support. It introduces new workshop patterns including a comprehensive dynamic-table pattern with filtering, pagination, and expandable rows, a file-upload pattern, and a chat pattern. Several component bug fixes improve combobox reliability, floating UI focus management, and toggle button state handling.
  </Typography>
  
  <Typography variant="subtitle-1" tag="h4">BREAKING CHANGES</Typography>
  - **Angular:** Drop Angular 18 support; library now requires Angular 19, 20, or 21

  <Typography variant="subtitle-1" tag="h4">Features</Typography>
  - **Surface:** Add surface variant classes for styling flexibility
  - **Dynamic Table:** Add comprehensive patterns with sorting, filtering, pagination, expandable rows, and action bars
  - **File Upload:** Add patterns with drag-and-drop, progress tracking, and validation
  - **Chat:** Add dialog-based, panel-based, and full-page chat patterns

  <Typography variant="subtitle-1" tag="h4">Bug Fixes</Typography>
  - **Combobox:** Reinstate automatic selection functionality
  - **Combobox:** Handle runtime undefined list case to prevent errors
  - **Floating UI:** Restore focus to trigger element when floating UI closes
  - **Floating UI:** Close menu on child click and properly bind disabled property
  - **Tab:** Fix disclosure tab bug when both expanded prop and disclosureTabToggled event are present
  - **Toggle Button:** Allow multiselect toggle group to return to empty state
  - **Toggle Button:** Fix initial state handling for multiselect mode
  - **Progress:** Allow indeterminate circular progress to be customized
  - **Pagination Control:** Prevent duplicate pages from appearing in start and end blocks
  - **File Upload:** Fix live region behavior for edge cases improving screen reader announcements
  - **Application Layouts:** Correct footer background color in layout patterns

  <Typography variant="headline-4" tag="h3">6.0.2 (2025-09-26)</Typography>
  <Typography variant="subtitle-1" tag="h4">Features</Typography>

  - **Library:** Nova Angular now supports Angular 18, 19, and 20
  - **Component:** List item
  - **Pattern:** Application layouts
  - **Pattern:** Wizard

  <Typography variant="headline-4" tag="h3">5.1.3 (2025-04-11)</Typography>
  <Typography variant="subtitle-1" tag="h4">Features</Typography>

  - Initial release of the component library.
  - Added a collection of components, utilities, and services.
    - Components
      - Accordion
      - Anchor link menu
      - Avatar
      - Badge
      - Banner
      - Breadcrumbs
      - Button
      - Checkbox
      - Chip
      - Color selector
      - Combobox
      - Content card
      - Date and time selectors
      - Dialog
      - Divider
      - Dropdown menu
      - Flag
      - Footer
      - Horizontal navigation
      - Icon
      - Input
      - Link
      - Listbox
      - Multiselect
      - Navigation drawer
      - Pagination
      - Panel
      - Progress
      - Radio
      - Section message
      - Select
      - Switch
      - Table
      - Tabs
      - Toggle
      - Tooltip
      - Vertical navigation
      - Wizard
    - Services
      - Accordion
      - App-ready
      - Combobox
      - Floating-ui
      - Id generator
      - Listbox
      - Nova lib
      - Pagination
    - Utilities
      - A11y
      - Breakpoints
      - Elevation
      - Flex
      - Open-in-new-tab
      - Spacing
      - Surface
      - Typography

</Changelog>


---

# index

---
title: Start building with Angular
description: Follow this step-by-step guide to start developing with the Visa Product Design System in Angular.
meta_description: Follow this step-by-step guide to start developing with the Visa Product Design System in Angular.
side_nav_title: Get started
side_nav_aria_label: Get started with Angular
is_nested_index: true
---

## Step 1: Update Angular

Nova Angular supports Angular 19, 20, and 21. See Angular's guide on how to
[upgrade Angular from your current version to the target version](https://angular.dev/update-guide?v=18.0-19.0&l=1).

## Step 2: Install the library

You can install the Nova Angular library using the package manager of your choice. Below we’ve provided the most common: NPM, PNPM, Yarn, and Bun.<br/><br/>

**Note:** Package managers can resolve dependencies differently and might not automatically install all required dependencies.

<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
<CodeSnippetTabs exampleName='nova-angular-installation' client:only="react" tabsList={['NPM', 'PNPM', 'Yarn', 'Bun']} code={code} language="typescript">
</CodeSnippetTabs>
</Utility>

<Typography variant="headline-4" tag="h3">Step 2b: Component-specific installs</Typography>

If you’re using Dialog, install the Angular cdk package.
<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
  <CodeSnippetTabs exampleName='nova-angular-dev-kit-installation' client:only="react" tabsList={['NPM', 'PNPM', 'Yarn', 'Bun']} code={cdk} language="typescript">
  </CodeSnippetTabs>
</Utility>

<br /><br />

Some package managers may require you to install our peer dependency packages if you don't have them already:
<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
  <CodeSnippetTabs exampleName='nova-angular-dependency-installation' client:only="react" tabsList={['NPM', 'PNPM', 'Yarn', 'Bun']} code={depInstalls} language="typescript">
  </CodeSnippetTabs>
</Utility>
<br />
***Note:** Install a version of @angular/forms that matches the version of Angular you are using.*

## Step 3: Set up the application

<Typography variant="headline-4" tag="h3">Step 3a: Import Nova styles</Typography>

Import the Nova styles library and theme in your angular JSON or equivalent file. Visa is the default theme, but can be replaced with other available themes. To learn more, visit [Theming](https://design.visa.com/base-elements/design-tokens/overview), and for more about Nova styles, visit [Get started for Styles (CSS)](https://design.visa.com/developing/styles-css).

<Utility vMarginTop={16}>
  <CodeSnippet
    isStandalone={true}
    exampleName='nova-angular-nova-styles-installation'
    client:only="react"
    code={stylesCode}
    language="JSON"
  />
</Utility>

<Typography variant="headline-4" tag="h3">Step 3b: Import the Nova Angular component library</Typography>

Import our library into your standalone component or NgModule.
<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
<CodeSnippetTabs exampleName='nova-angular-component-lib-import' client:only="react" tabsList={['Standalone components', 'NgModule' ]} code={componentImports} language="typescript">
</CodeSnippetTabs>
</Utility>

## Step 4: Add icons (optional)

Nova Angular can be used with Nova icons or a custom icon library. This documentation and the component examples use the Nova icons library. In addition, Angular icons are available as standalone icons or icon sprites. They can be imported into your standalone component file, or your NgModule.
<Typography variant="headline-4" tag="h3">Install Nova icons</Typography>

<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
<CodeSnippetTabs exampleName='nova-icons-angular-installation' client:only="react" tabsList={['NPM', 'PNPM', 'Yarn', 'Bun']} code={iconsInstallCode} language="typescript">
</CodeSnippetTabs>
</Utility>

<Typography variant="headline-4" tag="h3">Standalone icons (recommended)</Typography>

If you need just a few icons, you can import them directly from <VariableCodeFormatterTsx codeText={"@visa/nova-icons-angular"} />, then use the icons directly inside your HTML.

<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
<CodeSnippetTabs exampleName='nova-angular-standalone-icons' client:only="react" tabsList={['Standalone components', 'NgModule' ]} code={standaloneImports} language="typescript">
</CodeSnippetTabs>
</Utility>

<Typography variant="subtitle-1" tag="h4">HTML</Typography>

<Utility vMarginTop={16}>
  <CodeSnippet
    isStandalone={true}
    exampleName='nova-angular-standalone-icons-html'
    client:only="react"
    code={standaloneIconsHTML}
    language="html"
  />
</Utility>

<Typography variant="headline-4" tag="h3">Icon sprites</Typography>

If you need many icons or prefer a single import for all icons of a type, you can use icon sprites. Import them directly from <VariableCodeFormatterTsx codeText={"@visa/nova-icons-angular"} />, then use the icons inside your HTML.

<Utility vMarginTop={16}>
<CodeSnippetTabs exampleName='nova-angular-icon-sprites' client:only="react" tabsList={['Standalone components', 'NgModule' ]} code={spriteImports} language="typescript">
</CodeSnippetTabs>
</Utility>

<Typography variant="subtitle-1" tag="h4">HTML</Typography>

<Utility vMarginTop={16}>
  <CodeSnippet
    isStandalone={true}
    exampleName='nova-angular-icon-sprites-html'
    client:only="react"
    code={iconSpritesHTML}
    language="html"
  />
</Utility>

## Step 5: Use the components
After adding Nova icons, you're ready to use Angular components by copying and pasting the example code into your application. Check out [Button](https://design.visa.com/components/button)<!-- aria-label="Button component" --> to give it a try. 

<NeedHelp library="angular" />

---

# index

---
title: App ready check service
side_nav_title: App ready check
description: Ensure your application's stability and readiness by verifying browser and DOM functions.
meta_description: Ensure your application's stability and readiness by verifying browser and DOM functions.
---

## Component Code Examples: app-ready

This component is available in the following libraries:
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- Angular → `angular`

**Example (Angular 7.0.0)**:
```javascript
const libraryName = "angular"; // Determined from Step 1
const version = "7.0.0";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-angular-7.0.0.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the app-ready component
const component = parsed.components.find(c => c.name === 'app-ready');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `app-ready`

**Available in**:
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# index

---
title: Floating UI service
side_nav_title: Floating UI
meta_description: Create and manage floating elements seamlessly with our internal Floating UI service.
description: Create and manage floating elements seamlessly with our internal Floating UI service.
---

## Component Code Examples: floating-ui

This component is available in the following libraries:
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- Angular → `angular`

**Example (Angular 7.0.0)**:
```javascript
const libraryName = "angular"; // Determined from Step 1
const version = "7.0.0";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-angular-7.0.0.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the floating-ui component
const component = parsed.components.find(c => c.name === 'floating-ui');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `floating-ui`

**Available in**:
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# index

---
title: Uniqe ID generator service
side_nav_title: Unique ID generator
meta_description: Generate unique IDs for elements within applications, ensuring consistency and uniqueness.
description: Generate unique IDs for elements within applications, ensuring consistency and uniqueness.
---

## Component Code Examples: id-generator

This component is available in the following libraries:
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- Angular → `angular`

**Example (Angular 7.0.0)**:
```javascript
const libraryName = "angular"; // Determined from Step 1
const version = "7.0.0";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-angular-7.0.0.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the id-generator component
const component = parsed.components.find(c => c.name === 'id-generator');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `id-generator`

**Available in**:
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# index

---
title: Nova library service
side_nav_title: Nova library
meta_description: Access a suite of helper functions designed specifically for Nova components.
description: Access a suite of helper functions designed specifically for Nova components.
---

## Component Code Examples: nova-lib

This component is available in the following libraries:
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- Angular → `angular`

**Example (Angular 7.0.0)**:
```javascript
const libraryName = "angular"; // Determined from Step 1
const version = "7.0.0";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-angular-7.0.0.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the nova-lib component
const component = parsed.components.find(c => c.name === 'nova-lib');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `nova-lib`

**Available in**:
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# index

---
title: Accessibility utilities
side_nav_additional_screenreader_title: for Flutter
description: Create screen reader-friendly code in Flutter to enhance the accessibility of your apps.
---

<CodePage library={FLUTTER} />

---

# index

---
title: Changelog
side_nav_additional_screenreader_title: for Flutter
description: Keep up-to-date with the latest updates and enhancements in the Flutter changelog.
show_table_of_contents: false
---

<Changelog client:only="react" library="flutter">
    <SkeletonChangelog slot="fallback" />

    <Typography variant="headline-4" tag="h3">8.3.1 (2026-02-25)</Typography>
    <Typography variant="subtitle-1" tag="h4">Accessibility</Typography>

    - Improved `VComboboxScreen` component accessibility:
        - Added screen reader announcements for search result count changes
        - Added "No results found" and "\{count\} results found" announcements during search filtering
        - Enhanced clear button with proper semantics (`label`, `hint`, `button` role) and "Search field cleared" announcement
        - Improved close button semantics with descriptive label and hint
        - Added `liveRegion` semantics for empty results state
        - Enhanced list item accessibility with `selected` state, proper labels, and selection announcements
        - Wrapped list items with `Semantics` widget for better VoiceOver/TalkBack support

    <Typography variant="headline-4" tag="h3">8.3.0 (2025-11-19)</Typography>
    <Typography variant="subtitle-1" tag="h4">Added</Typography>

    - New `errorBorderColor` token in `VMessageColorSet` for WCAG-compliant form validation borders.
    - New `disabledIcon` token in `VDefaultThemeProps` and `VAltThemeProps` for disabled icon states.
    - Six new disabled-state color tokens for toggle switch (`trackDisabledOff`, `trackDisabledOn`, `thumbDisabled` and dark mode variants).
    - New `VSwitchStyle` properties for disabled state customization: `trackDisabledOff`, `trackDisabledOn`, `thumbDisabled`, `borderDisabledOff`, `borderDisabledOn`, `thumbBorderDisabled`.
    - New `VAccordion` properties: `initiallyExpanded`, `isExpanded`, `onExpansionChanged` for controlled accordion behavior.
    - New `VToggle` property: `isMultiSelect` for multi-select toggle support.
    - New `VBottomNavBarStyle` property: `indicatorColor` for tab bar selection indicator customization.
    - New `VBottomBarItems` property: `preserveIconColors` to preserve original icon colors in bottom navigation bar.
    - Added 99 new code examples across Accordion, Avatar, Badge, Banner, Button, Chip, Content Card, Dialog, Dropdown Menu, Link, List Item, Radio, Switch, Toggle, and Typography.
    - Added missing demo code examples for Accordion groups, Badge icon variants, Banner close icon, Button sizes and icon buttons, Chip read-only and group variants, Dropdown secondary and disabled variants, Link disabled and external variants, Radio individual buttons and panels, Switch states, and Toggle label variants.

    <Typography variant="subtitle-1" tag="h4">Changed</Typography>

    - Improved WCAG 2.1 Level AA compliance across all disabled states with full opacity colors.
    - Form validation error borders now use dedicated `errorBorderColor` token in dark mode.
    - Toggle switch disabled states now use full opacity colors instead of forced opacity.
    - Disabled icons in `VDropdownMenu`, `VInput`, and `VSelect` now use `disabledIcon` token.
    - `VToggleStyle` default `height` changed from 50.0 to 40.0.
    - `VToggleStyle` default `minimumWidth` changed from 50.0 to 44.0.
    - Fixed toggle label alignment, padding, active font styling, and multiselect behavior.
    - Fixed icon alternate color rendering.

    <Typography variant="subtitle-1" tag="h4">Fixed</Typography>

    - VPA accessibility gaps: form field error/validation text contrast in dark mode.
    - VPA accessibility gaps: toggle switch "Off" state contrast in light and dark modes.
    - VPA accessibility gaps: disabled icon color contrast (Face ID, empty states, dropdowns, inputs).
    - Regression fixes across Badge, Banner, Button, Toggle, Checkbox, Chips, Tab Bar, Top App Bar, and Radio.
    - Resolved all Dart analyzer warnings and info-level issues across the SDK codebase.

    <Typography variant="subtitle-1" tag="h4">Testing</Typography>

    - Added 6 new test files for material widget forks.
    - Added golden snapshot tests for all 28 components.
    - Expanded test suite to 740+ tests with 100% pass rate.

    <Typography variant="headline-4" tag="h3">8.2.0 (2025-09-26)</Typography>
    <Typography variant="subtitle-1" tag="h4">Features</Typography>

    - Added a collection of patterns:
        - Application layout
        - Chat
        - File Upload
        - Wizard
    - Added a new property enableInteractiveSelection to VInput.

    <Typography variant="headline-4" tag="h3">8.1.2 (2025-04-10)</Typography>
    <Typography variant="subtitle-1" tag="h4">Features</Typography>

    - Updated license in all files and pubspec.yaml

    <Typography variant="headline-4" tag="h3">8.1.1 (2025-03-26)</Typography>
    <Typography variant="subtitle-1" tag="h4">Features</Typography>

    - Updated pubspec.yaml

    <Typography variant="headline-4" tag="h3">8.1.0 (2025-03-26)</Typography>
    <Typography variant="subtitle-1" tag="h4">Features</Typography>

    - Initial release of the component library.
    - Added a collection of components:
        - Accordion
        - App Bar
        - Avatar
        - Badge
        - Banner
        - Bottom Navigation Bar
        - Button
        - Checkbox
        - Chip
        - Combobox
        - Content Card
        - Dialog
        - Divider
        - Dropdown Menu
        - Flag
        - Icon
        - Input
        - Link
        - List Item
        - Navigation Drawer
        - Panel
        - Progress
        - Radio
        - Section Message
        - Select
        - Switch
        - Tab
        - Toggle
        - Wizard

</Changelog>


---

# index

---
title: Start building with Flutter
description: Follow this step-by-step guide to start developing with the Visa Product Design System in Flutter.
meta_description: Follow this step-by-step guide to start developing with the Visa Product Design System in Flutter.
side_nav_title: Get started
side_nav_aria_label: Get started with Flutter
is_nested_index: true
---

## Step 1: Update Flutter

Nova Flutter supports Dart 2.19 and up with null safety, and our current Flutter SDK version is 3.29.2. To set up your Flutter development environment, visit the [Flutter App Pre-requisite and Setup Guide (internal only)](https://bookmarks.visa.com/Flutter%20Development%20Environment%20Setup) or [Choose your development platform to get started](https://docs.flutter.dev/get-started/install).

### Version

The version number reflects the number of developed components. Our current version is 8.3.1.

## Step 2: Install the library

### Set up pub.dev

You can install the Nova Flutter library [by setting up your Pub.dev environment](https://pub.dev/)<!-- aria-label="Flutter Pub Dev (opens in a new tab)" -->, then using the package below.

<Utility vMarginTop={16}>
    <CodeSnippet
        isStandalone={true}
        exampleName='nova-flutter-installation'
        client:only="react"
        code={installFromPubDev}
        language="zsh"
    />
</Utility>

## Step 3: Import Nova components

Import the library into your Dart code.

<Utility vMarginTop={16}>
    <CodeSnippet
        isStandalone={true}
        exampleName='nova-flutter-component-installation'
        client:only="react"
        code={importNova}
        language="dart"
    />
</Utility>

## Step 4: Add icons (optional)

We've created a dedicated widget, VIcon, to seamlessly integrate the SVG icon library with the components library. To best use Nova icons, import the library along side our visa_nova_flutter library.

<Utility vMarginTop={16}>
    <CodeSnippet
        isStandalone={true}
        exampleName='nova-flutter-icons'
        client:only="react"
        code={addIcon}
        language="dart"
    />
</Utility>

## Step 5: Use the components

After adding Nova icons, you're ready to use Flutter components by copying and pasting the example code into your application. Check out [Button](https://design.visa.com/components/button?code_library=flutter) to give it a try.

<NeedHelp library="flutter" />



---

# index

---
title: Start developing with VPDS
description: Learn how to start developing with the Visa Product Design System using this step-by-step guide for ease and efficiency.
meta_description: Learn how to start developing with the Visa Product Design System using this step-by-step guide for ease and efficiency.
side_nav_title: Get started
side_nav_aria_label: Get started
show_table_of_contents: false
---

## Browser Support

Our design system supports the latest versions of all major evergreen browsers, including Chrome, Firefox, Safari, and Edge. We do not support legacy or non-evergreen browsers.
<br/>
Why only evergreen browsers?
- Security: Evergreen browsers receive regular security updates, helping protect users and their data.
- Consistency: We use modern HTML and CSS features that are consistently supported across evergreen browsers, ensuring a reliable user experience.
- Performance: By focusing on up-to-date browsers, we can take advantage of the latest web standards for optimal performance.
- Maintainability: Supporting only evergreen browsers allows us to keep our codebase clean and efficient, without the need for legacy workarounds.
<br/>
For the best experience, please use the latest version of your preferred browser.

## Step 1: Familiarize yourself with the system

Check out the Visa Product Design System documentation. It's filled with principles and best practices that will provide a solid foundation, even in the absence of a dedicated design or content team.

- Understand our foundational principles including [Accessibility](https://design.visa.com/global-accessibility-requirements) and [Inclusive design](https://design.visa.com/about-VPDS/inclusive-design) in About VPDS.
- Discover our system's visual and architectural standards used to ensure consistent digital experiences in [Base elements](https://design.visa.com/base-elements).
- Find usage, specs, and accessibility guidance for the building blocks of the system in [Components](https://design.visa.com/components).
- Find layouts for common tasks like uploading a file or requesting a one-time passcode in [Patterns](https://design.visa.com/patterns).
- Create insightful, inclusive, and accessible data experiences for everyone, everywhere with [Data visualization](https://design.visa.com/data-visualization).
- Discover all the essentials for writing product content like voice and tone, grammar, and alert messaging in [Content](https://design.visa.com/content).

## Step 2: Install the code library of your choice

VPDS supports core parts of the system in CSS, React, Angular, and Flutter. You can visit get started pages for [CSS](https://design.visa.com/developing/styles-css), [React](https://design.visa.com/developing/react), [Angular](https://design.visa.com/developing/angular), and [Flutter](https://design.visa.com/developing/flutter) with quick start guides for each library. 

## Step 3: Connect with us

Have questions or ideas? Subscribe to our email list, visit our office hours, or join us on Teams by visiting [Support](https://design.visa.com/support).

---

# index

---
title: Accessibility utilities
side_nav_additional_screenreader_title: for React
description: Create screen reader-friendly code in React to enhance the accessibility of your apps.
---

<CodePage library={REACT} />

---

# index

---
title: Changelog
side_nav_additional_screenreader_title: for React
meta_description: ""
description: Keep up-to-date with the latest updates and enhancements in the React changelog.
side_nav_order: 1
show_table_of_contents: false
---

<Banner>
    <MessageIcon />
    <BannerContent className="v-pl-2 v-pb-2">
    <Typography>For step-by-step instructions on upgrading from Nova React v2.x to v3.x, refer to the [migration guide](https://github.com/visa/nova-react/blob/main/MIGRATION-GUIDE.md)<!-- aria-label="Migration guide" -->.</Typography>
    </BannerContent>
</Banner>

<br />

<Changelog client:only="react" library="react"  >
  <SkeletonChangelog slot="fallback" />
  <Typography variant="headline-4" tag="h3">3.1.0 (2026-03-20)</Typography>
  <Typography variant="body-1" tag="p">This release introduces new component properties, hooks, and pattern improvements. Key additions include the <VariableCodeFormatter codeText={"useModel"} /> hook for form state management, enhanced pagination controls with compact mode and controlled state, and expanded table customization options.</Typography>

  <Typography variant="subtitle-1" tag="h4">Features</Typography>

  - **Button:** Allow button to accept primary type
  - **Label:** All labels now extend typography
  - **Table:** Added `tableSize` property
  - **useModel:** Added new hook for form state management
  - **usePagination:** Added compact mode
  - **usePagination:** Optional props for provided/controlled state
  - **useTabs:** Allows controlled selected index value
  - **Utility:** `vFlexRow` now adds `vFlex` by default
  - **Dynamic Table:** Complete default pattern example with base shared components
  
  <Typography variant="subtitle-1" tag="h4">Bug Fixes</Typography>
  
  - **Application Layouts:** Footer background color now applies correctly
  - **Components:** Removed `defaultProps` to suppress React 19 deprecation warning
  - **Dropdown:** Dropdown items padding corrected
  - **Screen Reader:** Correct component selector typo in API
  - **Chat:** Pattern examples now use `hideTimestamp` prop for consistency
  - **Chat:** Adds validation reset and responsive behavior
  - **Chat:** Responsive padding on chat bubbles
  - **Chat:** Uses dialog content for dark mode
  - **File Upload:** Upload dialog flexible with boundaries
  - **File Upload:** Prevent card shift from uploading text
  - **File Upload:** Lowercases file extensions in display text
  - **Dynamic Table:** Remove nested components for proper React rendering

  <Typography variant="headline-4" tag="h3">3.0.0 (2025-09-26)</Typography>
  <Typography variant="subtitle-1" tag="h4">Features</Typography>

  - Added a collection of patterns:
    - Application layout
    - Chat
    - File Upload
    - Wizard

  <Typography variant="headline-4" tag="h3">2.5.4 (2025-04-11)</Typography>
  <Typography variant="subtitle-1" tag="h4">Features</Typography>

  - Initial release of the nova-react library.
  - Added a collection of components:
    - Accordion
    - Anchor link menu
    - Avatar
    - Badge
    - Banner
    - Breadcrumbs
    - Button
    - Checkbox
    - Chip
    - Color selector
    - Combobox
    - Content card
    - Date and time selectors
    - Dialog
    - Divider
    - Dropdown menu
    - Flag
    - Footer
    - Horizontal navigation
    - Icon
    - Input
    - Label
    - Link
    - Listbox
    - Logo
    - Multiselect
    - Navigation drawer
    - Pagination
    - Panel
    - Progress
    - Radio
    - Section message
    - Select
    - Switch
    - Table
    - Tabs
    - Toggle button
    - Tooltip
    - Vertical navigation
    - Wizard
  - Added several hooks:
    - use-accordion
    - use-card-number-validation
    - use-debounce
    - use-focus-trap
    - use-listbox
    - use-pagination
    - use-tabs
    - use-wizard
  - Added Utility and UtilityFragment components.

</Changelog>

---

# index

---
title: useCardNumberValidation
description: Learn how to utilize the useCardNumberValidation hook to validate card numbers.
meta_description: Learn how to utilize the useCardNumberValidation hook to validate card numbers.
---

## Component Code Examples: use-card-number-validation

This component is available in the following libraries:
- **React** (@visa/nova-react)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- React → `@visa/nova-react`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- React → `react`

**Example (React 3.1.0)**:
```javascript
const libraryName = "react"; // Determined from Step 1
const version = "3.1.0";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-react-3.1.0.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the use-card-number-validation component
const component = parsed.components.find(c => c.name === 'use-card-number-validation');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `use-card-number-validation`

**Available in**:
- React: versions 3.1.0, 3.0.0, 2.5.4

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples


---

# index

---
title: useDebounce
description: Learn how to utilize the useDebounce hook to delay the execution of an expensive function.
meta_description: Learn how to utilize the useDebounce hook to delay the execution of an expensive function.
---

## Component Code Examples: use-debounce

This component is available in the following libraries:
- **React** (@visa/nova-react)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- React → `@visa/nova-react`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- React → `react`

**Example (React 3.1.0)**:
```javascript
const libraryName = "react"; // Determined from Step 1
const version = "3.1.0";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-react-3.1.0.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the use-debounce component
const component = parsed.components.find(c => c.name === 'use-debounce');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `use-debounce`

**Available in**:
- React: versions 3.1.0, 3.0.0, 2.5.4

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples



---

# index

---
title: useFocusTrap
description: Learn how to utilize the useFocusTrap hook to confine focus within a specified container.
meta_description: Learn how to utilize the useFocusTrap hook to confine focus within a specified container.
---

## Component Code Examples: use-focus-trap

This component is available in the following libraries:
- **React** (@visa/nova-react)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- React → `@visa/nova-react`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- React → `react`

**Example (React 3.1.0)**:
```javascript
const libraryName = "react"; // Determined from Step 1
const version = "3.1.0";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-react-3.1.0.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the use-focus-trap component
const component = parsed.components.find(c => c.name === 'use-focus-trap');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `use-focus-trap`

**Available in**:
- React: versions 3.1.0, 3.0.0, 2.5.4

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples


---

# index

---
title: Start building with React
description: Follow this step-by-step guide to start developing with the Visa Product Design System in React.
meta_description: Follow this step-by-step guide to start developing with the Visa Product Design System in React.
side_nav_title: Get started
is_nested_index: true
side_nav_aria_label: Get started with React
---

## Step 1: Update React

Nova React supports React 19 and up. Visit React’s guide on how to upgrade to  [React 19](https://react.dev/blog/2024/04/25/react-19-upgrade-guide)<!-- aria-label="upgrade to react 18 (opens in a new tab)" --> for more. 

## Step 2: Install the library

You can install the Nova React library and the Nova styles library using the package manager of your choice. Below we’ve provided the most common: NPM, PNPM, Yarn, and Bun.
<br/>
**Note:** Package managers can resolve dependencies differently and might not automatically install all required dependencies.
<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
    <CodeSnippetTabs exampleName='nova-react-installation' client:only="react" tabsList= {['NPM', 'PNPM', 'Yarn', 'Bun']} code={ installationReact } language="javascript">
    </CodeSnippetTabs>
</Utility>

## Step 3: Set up the application
### Import Nova styles

Next, import the Nova styles library and your desired theme at the root level of your React project. The Visa theme is the default. To learn more, visit [Theming](https://design.visa.com/base-elements/design-tokens/overview), and for more about Nova styles, visit [Get started with Styles (CSS)](https://design.visa.com/developing/styles-css).
<Utility vMarginTop={16}>
<CodeSnippet
    isStandalone={true}
    exampleName='nova-react-nova-styles-import'
    client:only="react"
    isTabs={false}
    code={importStylesReact}
    language="javascript"
/>
</Utility>

## Step 4: Add icons (optional) 

For React, each icon has been developed as a React component, allowing you to selectively choose the icons you need. The library is designed to support deep tree shaking, ensuring that only the icons you use are bundled with your app. This optimization reduces build and load times as well as app sizes. The React library also provides native support for TypeScript, along with full support for all SVG properties and refs.
<br/>
Once you’ve installed the icon library, you can use them as components inside your TSX or JSX.

<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
    <CodeSnippetTabs  exampleName='nova-react-icons-import' client:only="react" tabsList= {['TypeScript', 'JavaScript']} code={ useIconsReact } language="javascript">
    </CodeSnippetTabs>
</Utility>

## Step 5: Use the components

After adding Nova icons, you're ready to use React components by copying and pasting the example code into your application. Check out below how to put our components to use with a few sample components. 

<Utility vMarginTop={16} vFlex vFlexCol vGap={12} class="post__content">
    <CodeSnippetTabs exampleName='nova-react-usage' client:only="react" tabsList= {['TypeScript', 'JavaScript']} code={ useComponentsReact } language="javascript">
    </CodeSnippetTabs>
</Utility>

<NeedHelp library="react" />

---

# index

---
title: Action primary
description: Use these generic styles to enhance user interactions with primary buttons designed for accessibility, or customize and create your own components.
---

## Component Code Examples: action-primary

<!-- Component data not available for: action-primary -->

This component may not be available in the library documentation system.


---

# index

---
title: Action secondary
description: Use these generic styles to enhance user interaction with secondary buttons that complement primary actions, or customize and create your own components.
---

## Component Code Examples: action-secondary

<!-- Component data not available for: action-secondary -->

This component may not be available in the library documentation system.

---

# index

---
title: Input
description: Use these generic styles to handle user data entry with various input components, and to customize and create your own components.
---

## Component Code Examples: input

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the input component
const component = parsed.components.find(c => c.name === 'input');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `input`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# index

---
title: Message
description: Use these generic styles to communicate important information with message components, or customize and create your own components.
---

## Component Code Examples: message

<!-- Component data not available for: message -->

This component may not be available in the library documentation system.

---

# index

---
title: Accessibility styles
side_nav_additional_screenreader_title: for Styles (CSS)
description: Create screen reader-friendly code in CSS to enhance the accessibility of your apps.
---

<CodePage library={CSS} />

---

# index

---
title: Changelog
side_nav_additional_screenreader_title: for Styles (CSS)
description: Keep up-to-date with the latest updates and enhancements in the Styles (CSS) changelog.
show_table_of_contents: false
---

<Changelog client:only="react" library="styles"  >
    <SkeletonChangelog slot="fallback" />

    <Typography variant="headline-4" tag="h3">1.6.5 (2026-03-19)</Typography>
    <Typography variant="subtitle-1" tag="h4">Features</Typography>

    - Added Surface 2 and Surface 3 examples.

    <Typography variant="subtitle-1" tag="h4">Bug Fixes</Typography>

    - Improved dark mode support for color, date, and time inputs.
    - Fixed table row scope attributes and adjusted inline table padding.
    - Fixed Select RTL support.
    - Fixed Select options background color styling.
    - Improved link wrapping behavior with trailing icons.
    - Updated Typography active color variable.

    <Typography variant="headline-4" tag="h3">1.6.4 (2025-09-26)</Typography>
    <Typography variant="subtitle-1" tag="h4">Features</Typography>

    - Added patterns:
        - Application layouts
        - Wizard
    - Added List item component.
    - Added several classes:
        - v-accordion-subtle
        - v-icon-success
        - v-icon-warning
        - v-icon-error
        - v-surface-2
        - v-surface-3
    - Consolidated themes.

    <Typography variant="headline-4" tag="h3">1.6.2 (2025-04-11)</Typography>
    <Typography variant="subtitle-1" tag="h4">Features</Typography>

    - Initial release of the component library.
    - Added a collection of components:
        - Accordion
        - Anchor link menu
        - Avatar
        - Badge
        - Banner
        - Breadcrumbs
        - Button
        - Checkbox
        - Chip
        - Color selector
        - Combobox
        - Content card
        - Date and time selectors
        - Dialog
        - Divider
        - Dropdown menu
        - Flag
        - Footer
        - Horizontal navigation
        - Icon
        - Input
        - Label
        - Link
        - Listbox
        - Logo
        - Multiselect
        - Navigation drawer
        - Pagination
        - Panel
        - Progress
        - Radio
        - Section message
        - Select
        - Switch
        - Table
        - Tabs
        - Toggle button
        - Tooltip
        - Vertical navigation
        - Wizard

</Changelog>

---

# index

---
title: Start building with Nova styles
description: Follow this step-by-step guide to developing web experiences with the Visa Product Design System.
meta_description: Follow this step-by-step guide to start developing web experiences with the Visa Product Design System.
side_nav_title: Get started
side_nav_aria_label: Get started with Styles (CSS)
is_nested_index: true
---

## Step 1: Install Nova styles
You can use NPM, PNPM, or Yarn to install Nova styles, depending on your preference or your project's requirements. Choose one of the following package managers for the installation.

<Utility className="not-markdown" vMarginTop={16}>
    <CodeSnippetTabs exampleName='nova-styles-installation' client:only="react" tabsList= {['NPM', 'PNPM', 'Yarn']} code={installationCSS} language="javascript">
    </CodeSnippetTabs>
</Utility>

## Step 2: Import Nova styles
Once Nova styles is installed, you need to import it in your project. This process might look different depending on whether you're using HTML, [React](https://design.visa.com/developing/react), or [Angular](https://design.visa.com/developing/angular). Follow the instructions for your setup below.

### HTML

If you're working with standard HTML, add a link to the Nova styles CSS file in your HTML file by replacing the actual path where the Nova styles files are located.

<Utility vMarginTop={16}>
    <CodeSnippet isStandalone={true} exampleName='nova-styles-import' client:only="react" isTabs={false} code={importStyles} language="html">
    </CodeSnippet>
</Utility>

## Step 3: Add icons (optional)
You can use Nova CSS to add [Icons](https://design.visa.com/components/icons-illustrations) to your web applications. Use individual SVGs for specific icons or SVG sprites to efficiently load and reuse a full set of icons across your app.

### Installing @visa/nova-icons-svg

<Utility className="not-markdown" vMarginTop={16}>
    <CodeSnippetTabs exampleName='nova-styles-installation' client:only="react" tabsList= {['NPM', 'PNPM', 'Yarn']} code={installationIconsSVG} language="javascript">
    </CodeSnippetTabs>
</Utility>

### Installing @visa/nova-icons-sprite

<Utility className="not-markdown" vMarginTop={16}>
    <CodeSnippetTabs exampleName='nova-styles-installation' client:only="react" tabsList= {['NPM', 'PNPM', 'Yarn']} code={installationIconsSprite} language="javascript">
    </CodeSnippetTabs>
</Utility>

### SVGs
SVG stands for Scalable Vector Graphics, which is an image format based on XML for creating two-dimensional graphics. The key feature of SVGs is their scalability, allowing them to be resized without losing quality. This makes them ideal for the web, where images need to look good on various screen sizes and resolutions. Additionally, SVGs are often much smaller in size compared to JPEGs and PNGs.

<Utility vMarginTop={16}>
    <CodeSnippet isStandalone={true} exampleName='nova-styles-icons-import' client:only="react" isTabs={false} code={addIconsCSS} language="javascript">
    </CodeSnippet>
</Utility>

### SVG sprites
A sprite is a collection of SVG icons combined into a single file. This method is commonly used to enable a single server request for all icons, making it the most efficient way to access a large number of icons, especially if many are likely to be used during a session.

#### Using SVG sprites

Import and use icons sprite from @visa/nova-icons-sprite. This will add all of the icons as a sprite into your project and then reference them as needed. It's up to you if you'd like to use the Visa sprite, the Generic sprite, or both.

<Utility vMarginTop={16}>
    <CodeSnippet isStandalone={true} exampleName='nova-styles-sprites-usage' client:only="react" isTabs={false} code={useSVGSpritesCSS} language="javascript">
    </CodeSnippet>
</Utility>

## Step 4: Use the components
After importing Nova styles and adding icons, you're ready to use its components by copying and pasting the example code into your application. Check out [Button](https://design.visa.com/components/button) to give it a try.

<NeedHelp library="Styles"/>

---

# design practices

---
title: Global accessibility requirements
description: Learn how to ensure people of diverse abilities can use and interact with our digital products and tools.
meta_description: Discover helpful design practices to ensure people of diverse abilities can use and interact with our digital products and tools.
tab_title: Design practices
date: 01/01/2021
---

Each person's experience with a disability is unique, and it’s important to avoid categorizing people by disability "type". Instead, approach accessibility by understanding the ways people with disabilities use and interact with digital technologies, and design for them using the best practices defined in this section.<br/><br/>
Designers can prevent about 70% of common accessibility issues by considering VGAR as they work. For additional context, [learn how users with various disabilities navigate web experiences](https://www.w3.org/WAI/people-use-web/user-stories/).

## Use of color
When using color to identify or differentiate elements, ensure the same information is available through alternative methods such as text or icons for users experiencing color blindness.
- Never use color alone to indicate a change in state including errors. 
- Combine two of the three elements to assist users: color, icon, and descriptive text.

<img src="https://design.visa.com/assets/about-vpds/accessibility/a11y-dp-color.svg" alt="An input field showing an error through the use of red color, error icon, and error descriptive text"/>

## Media controls
When using moving content, such as automatically-updating content or a slideshow carousel, clearly present users with the option to stop, pause, or hide the content. 
- Never use content that blinks or flashes automatically as this can induce seizures in users with photosensitive disorders.

<img src="https://design.visa.com/assets/about-vpds/accessibility/a11y-dp-media.svg" alt="A video player with a play button in the center"/>

## Sufficient contrast
Maintaining a minimum contrast ratio between foreground and background colors is crucial for readability. It ensures that content is easily distinguishable and readable, especially for users with visual impairments or color blindness. This adherence to contrast ratio requirements is a key aspect of creating an accessible and inclusive digital experience.
- Ensure that all content adapts to and supports the user's high contrast mode settings.

<img src="https://design.visa.com/assets/about-vpds/accessibility/a11y-dp-contrast.svg" alt="A paragraph of text with insufficient contrast and another that passes the required ratio"/>

### Contrast requirements

    Contrast ratio requirements by context

- Context: 4.5:1

- Context: 3:1

- Context: No requirement

- Context: 3:1

- Context: No requirement

## Responsive content
Responsive design is a cornerstone of accessibility, as it ensures content adapts well to different devices, screen sizes, and user preferences. This enhances the user experience, making your content more accessible and user-friendly for all.
- Always consider how your content will respond to changes like text resizing, spacing, and reflow.

<img src="https://design.visa.com/assets/about-vpds/accessibility/a11y-dp-responsive.svg" alt="A paragraph of text wraps and reflows on a small screen"/>

### Resizing and scaling

Resizing and scaling are key for accessibility as they allow users with visual impairments to enlarge content without losing functionality or ease of navigation. 
- Design content to scale effectively, ensuring it remains fully functional and doesn't require horizontal scrolling even when users increase the size to 400%.

### Increasing spacing

Content should adapt to increases in letter, word, line, and paragraph spacing. There should be no loss of content or functionality when:

- Line height or spacing is changed up to 1.5 times the font size.
- Paragraph spacing is changed up to 2 times the font size.
- Tracking or letter spacing is changed up to 0.12 times the font size.
- Word spacing is changed up to 0.16 times the font size. 
<br/>

Reference [Typography](https://design.visa.com/base-elements/typography) for further guidance.

## Navigation
Maintaining a consistent order for components across multiple pages is crucial for accessibility. It provides a predictable and intuitive navigation experience, particularly for users who rely on screen readers or keyboard navigation. 

- Provide users with more than one way to locate content within a set of web pages, except when the page is a step in a process or its end result.
- If a page has a login feature and focus is not automatically set to the login field on page load, the page must include a “Skip to login” link as the first link on the page. The link must move focus to the login field, and the link may be hidden from view until it has focus.
- A "Skip to main content" link must be included on every page as the first link (or second if "skip to login" link is present) on the page. The link must skip to the main content of the page or the error summary (if present) and may be visually hidden until it has focus.

<img src="https://design.visa.com/assets/about-vpds/accessibility/a11y-dp-navigation.svg" alt="A page layout with a navigation header and a Skip to content link below"/>

## Touch target areas
Ensuring sufficient space around interactive areas is vital as it facilitates easier interaction, particularly for users who may struggle with precise movements. When using components with smaller visual footprints, it's important to design with ample touch area in mind and avoid placing elements too closely together.

### Touch targets

Touch targets should be large and appropriately spaced for easy interaction by users with varying dexterity and vision.
<img src="https://design.visa.com/assets/about-vpds/accessibility/a11y-dp-touch.svg" alt="A button with a touch target area of 44 by 44 pixels"/>
Use the minimum size of 44x44dps for touch areas across all interactive components.

### Non-touch targets

Non-touch targets should be easily navigable and identifiable for users with varying levels of dexterity and vision.
<img src="https://design.visa.com/assets/about-vpds/accessibility/a11y-dp-nontouch.svg" alt="A button with an icon that is 24x24dps."/>
- Use the minimum size of 24x24dps for target areas across all interactive components.
- Rounded corners detract from 24x24dps target area.
- To learn more details and nuances around target areas, check out the WCAG guidance.

## Error feedback
Pages collecting user input need to validate entries and ensure all users are aware of errors. By providing clear and immediate feedback about errors, you can create a more accessible and user-friendly experience.
- Provide users with clear instructions on how to correct errors when applicable.
- Never use color alone to indicate a change in state including errors. 
- Combine two of the three elements to assist users: color, icon, and descriptive text.

<img src="https://design.visa.com/assets/about-vpds/accessibility/a11y-dp-error.svg" alt="An error in a section message and an inline error on an input field"/>

## Consistent identification
Using consistent identification for content with the same functions is crucial for accessibility. This allows users, especially those using assistive technologies like screen readers, to easily identify and understand the purpose of interactive elements such as links, buttons, and custom controls. By doing so, you enhance the predictability and usability of your content, making it more accessible to all users.
- Use consistent labels, names, and text alternatives for content with the same functions across experiences. 
<img src="https://design.visa.com/assets/about-vpds/accessibility/do-a11y-id.svg" alt="Buttons that have labels actions, and examples of links used to navigate"/>

## Labeling and instructions
Ensuring that form input controls have clear, descriptive labels and instructions helps users, particularly those with cognitive impairments or those using assistive technologies, to accurately identify specific components within the content. It also prevents incomplete or incorrect form submissions by providing users with the necessary information to fill out the form correctly. 
- Ensure that form input controls have clear, descriptive labels and instructions.
- Use universally understood icons and text to help users understand labels. 

## Hierarchy

Clear hierarchy is vital for accessibility. Always ensure that information, structures, and relationships conveyed through visual and auditory presentation formats are also programmatically determined or made available in text. By making this information available in a programmatically determined or text format, you ensure that it's accessible to all users, including those using assistive technologies like screen readers.
- Use headings and other visual cues to associate sections with related content and create a logical hierarchy.
- Content in a list format must use the correct ordered (ol) or unordered list (ul) markup.
- Learn more about structure in our [Content guidelines](https://www.figma.com/proto/nheFDgsLWgVSKTMq1Vbldg/Nova--Notation?type=design&node-id=3027-261561&t=3Nv8k2h0eGI4HWhJ-0&scaling=min-zoom&page-id=1376%3A130977&starting-point-node-id=1696%3A175077). 

<img src="https://design.visa.com/assets/about-vpds/accessibility/a11y-hierarchy.svg" alt="A page layout with clear visual hierarchy"/>

For further guidance on headings and hierarchy, refer to [Typography](https://design.visa.com/base-elements/typography) and [Information architecture](https://design.visa.com/content/information-architecture).

## Text-based alternatives

Providing accurate text alternatives for images and non-text content ensures the same information is conveyed with the same context and purpose to users who cannot perceive the original content due to visual impairments or those using assistive technologies like screen readers. By ensuring this information can be rendered through any sensory modality, you make your content more accessible.
- Ensure images and non-text content have accurate text alternatives that provide the same information, context, and purpose to users and can be rendered through any sensory modality.
- Always present text using live text and CSS, not images of text. The only exceptions are instances where images of text are unavoidable, such as logos, graphs, and screenshots.

<img src="https://design.visa.com/assets/about-vpds/accessibility/a11y-dp-text-based.svg" alt="A graphic of a mountain range with alt text describing the same"/>

## Multimedia content
Accurate closed captioning for all dialogue in video content allows all users to fully engage with the content. Additionally, they can be beneficial for individuals who may not have their sound turned on or for whom English is a second language. By ensuring all video content is accurately captioned, you make your content more accessible to a wider range of users.
- If the video provides information visually that the accompanying audio doesn’t describe, include an audio description track specifically explaining that information.
- If the audio description track can’t adequately explain the visual information during gaps in the dialogue, use an extended audio description.
- Add pauses at appropriate times in the video to allow the description to finish.

<img src="https://design.visa.com/assets/about-vpds/accessibility/a11y-dp-multimedia.svg" alt="A media player with a full set of controls as well as subtitles and a link to a transcript"/>

## States

Learn about visual cues and design requirements that help users understand component interactivity in [States](https://design.visa.com/base-elements/states).


---

# development and testing practices

---
title: Global accessibility requirements
description: Learn how to ensure people of diverse abilities can use and interact with our digital products and tools.
meta_description: Learn how to reduce the time spent in manual testing by writing accessible code and using automated tools to check development work.
tab_title: Development and testing practices
thumbnail: assets/about-vpds/accessibility/accessibility.svg
date: 01/01/2021
header_image: assets/about-vpds/accessibility/accessibility-overview.svg
---

Developers can reduce the time spent in manual testing by writing accessible code and using automated tools to check their work. Refer to VGAR to validate and iterate on work throughout the accessibility journey.

## Doctype declaration
HTML doctype is a required preamble. Without a valid doctype declaration, browsers tend to use a different rendering mode (such as no-quirks mode, quirks mode, limited-quirks mode, etc.) that is incompatible with some specifications. The `<!DOCTYPE html>` doctype is required for legacy reasons. Provide a valid and accurate doctype for all web pages.

## Page title
The page `title` element represents the name of a document and identifies the relevance of information contained in a web page. Provide accurate, descriptive, and unique page titles. Use consistent structures for titles across web pages.

## Language
Identifying the language of a web page helps assistive technologies render text accurately. Provide the `lang` attribute specifying the primary language for the contents of an element and for any of that element's attributes containing text. When content is written in multiple languages, these requirements help assistive technologies present it according to the rules for each language. For instance, screen readers will invoke correct pronunciation rules, visual browsers will display characters and scripts accurately, and media players will show captions correctly.

## Hidden content
Content that may need to be hidden from sighted users, but not screen readers, must be moved off-screen using CSS.
<br/>
Wrap this content in a `div` with `role=&quot;presentation&quot;` and `aria-hidden=&quot;true&quot;`. Additionally, set `tabindex=&quot;-1&quot;`.
<br/>
Content that may need to be hidden from both sighted and screen reader users should be removed from the DOM using CSS `visibility:hidden` or `display:none` and `aria-hidden=&quot;true&quot;`.

## Structure and semantics
Headings are useful for organizing content into contextual sections, establishing content hierarchy, and enabling screen reader users to jump directly to specific content. They need to be defined with valid markup and structured in a proper nesting order to ensure assistive technologies can present them properly.
- Any text element which conveys information through its visual presentation style must be indicated semantically in code. This includes text styling such as strong, cite, blockquote, sub, and sup, and any other text style which carries secondary meaning.
- Paragraphs must be marked up as paragraphs.
- Groups of items, such as a navigation menu or group of tabs, must be marked up as a list.
<br/>
To ensure that assistive technologies encounter the content in the same order as the logical presentation of the content, it should be structured in a logical order in the HTML code. Do not use CSS to order content. Additionally, any content that is not shown until a specific time or event should be removed from the DOM or parked at the bottom of the DOM.

## Forms and controls
Ensure that assistive technologies (AT) can gather information on, activate (or set), and update the status of user interface controls in the content.
<br/>
Form controls that use a label to identify them must have only one label programmatically associated with them.
- Use `for=&quot;<ID of control>&quot;`, `aria-labelledby`, or `aria-label` for for this label.
<br/>
Communicate required controls in text either at the beginning of the form or in-line.
- Use the `aria-required=&quot;true&quot;` attribute.
<br/>
Groups of checkboxes should indicate the required state in text either at the beginning of the form by stating all fields are required, or in the group’s `fieldset` legend instead.
- Do not use the `aria-required` attribute.
<br/>
Helper text must be programmatically associated with a form control.
- Use `aria-describedby=&quot;<ID of helper text container>&quot;`.
<br/>
If there are multiple pagination controls on a page, they must have unique labels but still contain the word &quot;Pagination&quot;.
- Use `role=&quot;navigation&quot;` and `aria-label=&quot;Pagination&quot;`.

## Error identification and suggestions
Controls being validated for errors must include `aria-invalid=&quot;true&quot;` when an error is present.
- Keyboard focus must be automatically set to the first invalid form control when an error is detected using validation after the user submits the form.
- When an error is detected using client-side validation, set `aria-invalid=&quot;true&quot;` and add the ID of the error helper text container to the `aria-describedby` attribute.

When an error is detected using in-line validation, any previous `role=&quot;alert&quot;` instances must be removed from the DOM and `role=&quot;alert&quot;` must be set on the container of the `error_helpertext`.

## System messages and navigation
System messages must include the `role=&quot;status&quot;` and `aria-live=&quot;assertive&quot;` attributes on the message container when added to the DOM. Only add system messages to the DOM after a button press or on page load so that they don’t interrupt the user’s workflow.<br/><br/>

At minimum, the page must have a `main` landmark region defined, and `banner`, `navigation`, `search`, `complementary`, and `contentinfo` roles if these content types are present in the page.
- If a page has multiple landmarks of the same type, such as main navigation and sub-navigation, those regions must have unique names applied using an appropriate naming technique. Do not include the landmark role type in the name.

## Dialogs
Modal dialog windows must have `role=&quot;dialog&quot;` and `aria-modal=&quot;true&quot;` on the modal container.<br/><br/>

Modal dialogs must have `aria-labelledby=&quot;id of dialog-title&quot;` where &quot;dialog-title&quot; would be the modal dialog’s title, such as its main heading.<br/><br/>

Modal dialogs should have `aria-describedby=&quot;dialog-desc&quot;` where &quot;dialog-desc&quot; is helpful information above the first focusable element.<br/><br/>

Modal dialogs must have focus set to an appropriate location based on the content presented in the modal dialog.
- Modal dialog windows must trap focus inside the modal dialog.
- Dialogs must restore focus to their triggering element when the dialog is closed.<br/><br/>

Modal dialogs must allow the user to move through the modal dialog’s focusable elements, “wrapping around” from bottom-to-top and top-to-bottom using the <kbd>Tab</kbd> <kbd>Shift</kbd> + <kbd>Tab</kbd> key and keyboard events.<br/><br/>

Modal dialogs must prevent mouse-clicks that occur outside the modal dialog from having any effect on the modal dialog.<br/><br/>

If a heading is used in a dialog, the first heading level must be `H2` followed by appropriate heading levels.

Dialog windows must have the <kbd>Esc</kbd> keyboard event set to close the dialog.

## Tables
Tables must never be used for layout purposes. Data tables must use proper table headers `<th>`, and every table header must have the scope attribute set to `scope=&quot;col”` or `scope=&quot;row&quot;`, unless it would invalidate a data relationship. If necessary, the header attribute can be used to hard code how headers should be read to screen reader users.<br/><br/>

Data tables must be identified for screen readers by including the “title&quot; of the table in its `<caption>` element (the caption may be hidden visually with CSS). If the table has more than 4 table headings, a caption must be included to summarize its layout and functional relationships.

## Text alternatives
All non-text content must include text alternatives that provide equivalent information, context, and purpose to the user. Non-text content with `<img>` elements provide the text alternative using the `alt` attribute. For non-text content using `role=&quot;img&quot;`, use `aria-label`, `aria-labelledby`, or visibly hidden text.<br/><br/>

All decorative non-text that provides no contextual value or is already defined by surrounding content must be hidden from screen reader users. For `<img>` elements, use `alt=&quot;&quot;`. For everything else, use `aria-hidden=&quot;true&quot;`.

## Keyboard interaction
All functionality and content must be available via the keyboard only and should not require the specific timing of keystrokes. If keyboard focus is ever controlled by part of the UI, such as a PDF viewer or modal window, it must allow focus to return to the launching element and browser through keyboard commands only.
<br/>
Keyboard users should be able to use the Tab key to navigate through the page in the same order as the visual presentation of the content. This tab order should be established by the HTML structure of the page. As the user moves through the page with the keyboard, a highly visible indication of keyboard focus should appear on each element as it receives focus.
<br/>
Content that remains hidden until it becomes visible on mouse hover must also be shown when it receives keyboard focus and hidden again when focus is removed.
Content that appears and disappears in coordination with keyboard focus or pointer hover—such as tooltips, sub-menus, and other non-modal popups—must be dismissable, hoverable, and persistent.

## Screen reader compatibility
All features and functionality must work with at least one screen reader per platform. Features and functionalities including but not limited to alerts, visual changes on the page, page titles, iframes (used for user interaction, but not system use), landmarks, headings, links etc., must be presented and read accurately by supported screen readers.


---

# index

---
title: Global accessibility requirements
description: Learn how to ensure people of diverse abilities can use and interact with our digital products and tools.
meta_description: Find practical resources to ensure people of diverse abilities can use and interact with our digital products and tools.
thumbnail: assets/about-vpds/accessibility/accessibility.svg
date: 01/01/2021
tab_title: Overview
header_image: assets/about-vpds/accessibility/accessibility-overview.svg
related:
  content:
    - inclusive-language
  aboutVPDS:
    - inclusive-design
---

<Breakless>

The Visa Global Accessibility Requirements (VGAR) are a set of functional expectations that distill Web Content Accessibility Guidelines (WCAG) into easy-to-learn resources for product teams, customers, and partners. These requirements help ensure Visa’s digital products meet accessibility standards and should be used to guide product planning, design, and development. 

To scale accessibility at Visa, we’ve established a unified internal standard for building accessible products. The Visa Global Accessibility Requirements (VGAR) helps teams focus on building rather than interpreting accessibility standards.

- **Communicates how we implement WCAG 2.2 AA standards** in practice to our employees, clients, and partners.
- **Provide an easy-to-follow testing methodology** for web and mobile products.
- **Centrally manage and stay up-to-date** with current accessibility trends.

## Requirements and test procedures

Visa Global Accessibility Requirements outline the expected behavior for accessible user experiences across web, mobile, PDF, and email experiences. Visa teams follow these requirements during design and development.

Each requirement includes specific test procedures to validate compliance at every stage. Visa teams run both automated and manual tests to ensure all applicable requirements are met.

## WCAG 2.2 AA
At Visa, we aim to build all web and mobile components to conform to level AA of the Web Content Accessibility Guidelines 2.2 (WCAG 2.2), the internationally recognized benchmark for building accessible websites developed by the [World Wide Web Consortium (W3C)](https://www.w3.org/) for enhancing web accessibility. W3C is an international body that develops open standards for the web, and WCAG 2.2 focuses on making web content accessible to all, regardless of abilities. Visit [WCAG 2.2](https://www.w3.org/TR/WCAG22/) to learn more about current web content accessibility guidelines.

## Connect with us
Have questions or ideas? Visit our office hours, join Visa Accessibility on Teams, or get general VPDS help by visiting [Support](https://design.visa.com/support/).

</Breakless>


---

# index

---
title: Application
side_nav_title: Application
description: Find application requirements for testing mobile experiences.
side_nav_aria_label: Application requirements for mobile.
side_nav_order: 0

---

<Breakless>

## Vision support (APP-1)

### Custom display & text settings (APP-1-1)
Text content adapts to Larger Text setting.

#### How to test
**Tool:** Visual inspection

1. Adjust OS level settings for Larger Text:
    - iOS: Settings > Accessibility > Display & Text Size > Larger Text On. Set the size to the  third notch from the largest accessibility size (notch 8 of 11).
    - Android: Settings > Display > Font Size and Style > maximum setting.
2. Confirm that all text content adapts when applied.

#### Test outcomes
- **Pass**: All text content adapts to larger text setting when applied.

- **Fail**: Some or all text content does not adapt to larger text setting when applied.

#### Related WCAG criteria
[WCAG 2.2 AA - 1.4.4 Resize Textsize Text](https://www.w3.org/TR/WCAG22/#resize-text)

---

### Support screen reader (APP-1-2)
VoiceOver/TalkBack can be used to successfully interact with the full app experience

#### How to test
**Tool:** VoiceOver (iOS), TalkBack (Android)

1. Interact with the full app experience and task flows using VoiceOver/TalkBack.
2. Confirm that all functionality can be used easily and effectively by the screen reader.

#### Test outcomes
- **Pass**: All features and functionality can be easily and successfully used with VoiceOver/TalkBack.

- **Fail**: Some features and functionality cannot be easily and successfully used with VoiceOver/TalkBack.

#### Related WCAG criteria
[502.2.2 No Disruption of Accessibility Features](https://www.access-board.gov/ict/)

---

### View titled (APP-1-3)
Each screen/view needs to be titled and the title needs to be an accurate and descriptive title for the content presented on that screen/view.

#### How to test
**Tool:** VoiceOver (iOS), TalkBack (Android)

1. Navigate to each view using the screen reader.
2. Confirm that each view has a title read aloud by VoiceOver/TalkBack.

#### Test outcomes
- **Pass**: All views have a title that will be read by VoiceOver or TalkBack.

- **Fail**: One or more views are not titled.

#### Related WCAG criteria
[WCAG 2.2 A - 2.4.2 Page Titled](https://www.w3.org/TR/WCAG22/#page-titled)

---

## Physical and motor support (APP-2)

### Flexible orientation (APP-2-1)
Content is not restricted to one orientation, unless that orientation is essential, to allow users to orient the device according to their needs and personal setup.

#### How to test
**Tool:** Visual inspection

1. Enable setting to allow orientation to switch based on how the device is oriented.
2. Open the application being tested and confirm that each screen adapts to the portrait or landscape orientation change when the device is rotated between these orientations.

#### Test outcomes
- **Pass**: All content adapts to current orientation as expected.

- **Fail**: Some content that does not fall under the exception criteria in assumptions does not adapt to the current orientation as expected.

- **NA**: The full app experience falls under the exception criteria in assumptions.

#### Related WCAG criteria
[WCAG 2.2 AA - 1.3.4 Orientation](https://www.w3.org/TR/WCAG22/#orientation)

---

### Motion control (APP-2-2)
When device motion is used to control the interface there is a way to deactivate it and operate the same functionality through UI controls instead

#### How to test
**Tool:** Visual inspection

1. Determine whether device motion is used to control the interface.
2. If device motion is used to control the interface, confirm that there is a way to deactivate motion control and operate the same functionality through UI controls instead.

#### Test outcomes
- **Pass**: Motion input is used but it can be deactivated and an alternative is provided.

- **Fail**: Motion input is used and cannot be disabled or an alternative to motion is not provided.

- **NA**: Motion input is not used to control the interface.

#### Related WCAG criteria
[WCAG 2.2 A - 2.5.4 Motion Actuation](https://www.w3.org/TR/WCAG22/#motion-actuation)

---

### Multiple authentication methods (APP-2-3)
User authentication must avoid relying on a cognitive function test by providing multiple means of filling in authentication information.

#### How to test
**Tool:** Visual inspection

Ensure that authentication form fields allow any of the following:
- The fields allow autofill of information.
- Information may be pasted into the form fields.
- Biometrics can be used to sign into accounts.

#### Test outcomes
- **Pass**: The authentication fields allow autofill of stored information OR information can be copied and pasted into the fields OR biometrics (fingerprints, facial-scan, etc.) can be used to log in.

- **Fail**: The authentication fields do not allow autofill AND information cannot be copied and pasted into the fields AND biometrics cannot be used (for example: none of the pass criteria methods are used).

- **NA**: The view does not require interaction to authenticate.

#### Related WCAG criteria
[WCAG 2.2 AA - 3.3.8 Accessible Authentication](https://www.w3.org/TR/WCAG22/#accessible-authentication-minimum)

---

## Diverse user needs (APP-3)

### App language (APP-3-1) 
The application language can be programmatically determined

#### How to test
**Tool:** VoiceOver (iOS) / Talkback (Android)

1. Use the screen reader to interact with the application content.
2. Ensure that the screen reader output matches the correct language for each language supported.

#### Test outcomes
- **Pass**: The screen reader output matches the language of the application.

- **Fail**: The screen reader output does not match the language of the application.

#### Related WCAG criteria
[WCAG 2.2 A - 3.1.1 Language of Page](https://www.w3.org/TR/WCAG22/#language-of-page)

---

### Warn about timeout (APP-3-2)
Users must be warned prior to when a session times out and expires. 

#### How to test
**Tool:** Visual inspection

Confirm that users are warned prior to when a session times out and expires.

#### Test outcomes
- **Pass**: Session timeout warning occurs prior to session time out and expiration.

- **Fail**: Session timeout occurs without warning.

- **NA**: No session timeout is present.

#### Related WCAG criteria
[WCAG 2.2 A - 2.2.1 Timing Adjustable](https://www.w3.org/TR/WCAG22/#timing-adjustable)

---

### Extend timeout (APP-3-3)
When a session timeout warning occurs, users MUST be given at least 30 seconds to take action in order to avoid a session timeout by extending the time limit via a simple user action.

#### How to test
**Tool:** Visual inspection

Confirm that users are given at least 30 seconds to take action in order to avoid a session time out by extending the time limit of a session.

#### Test outcomes
- **Pass**: Users are given at least 30 seconds to extend the session.

- **Fail**: Users are given less than 30 seconds to extend the session.

- **NA**: No session timeout is present.

#### Related WCAG criteria
[WCAG 2.2 A - 2.2.1 Timing Adjustable](https://www.w3.org/TR/WCAG22/#timing-adjustable)

---

### Use an automated testing tool (APP-3-4)
For iOS devices, all Xcode - Accessibility Inspector Audit tests pass during development

For Android devices, all Accessibility Scanner tests pass during development

#### How to test
**Tool:** Xcode - Accessibility Audit (iOS)/Accessibility Scanner (Android

1. Open your app in Xcode for iOS or Accessibility Scanner for Android.
2. Start the accessibility tool used on your platform.
3. Ensure that there are no automated errors present.

#### Test outcomes
- **Pass**: Zero issues are found OR issues found are determined to be false positives by Visa Accessibility.

- **Fail**: One or more issues are found.

#### Related WCAG criteria
[WCAG 2.2 A & AA](https://www.w3.org/TR/WCAG22/)

</Breakless>

---

# index

---
title: Content
side_nav_title: Content
description: Find content requirements for testing mobile experiences.
side_nav_aria_label: Content requirements for mobile.
side_nav_order: 1

---

<Breakless>

## Audio and video media (CON-1)

### Transcripts for audio-only / video-only (CON-1-1)
For audio-only and video-only media, a transcript must be provided which provides the same information as presented in the original media content.

#### How to test
**Tool:** Visual inspection

1. Identify any audio-only or video-only media content.
2. Confirm that a transcript which provides the same information as presented in the original media content is available for all audio-only and/or video-only content.

#### Test outcomes
- **Pass**: Transcripts are provided.

- **Fail**: Transcripts are not provided.

- **NA**: No audio or video only content is present.

#### Related WCAG criteria
[WCAG 2.2 A - 1.2.1 Audio-only and Video-only (Prerecorded)](https://www.w3.org/TR/WCAG22/#audio-only-and-video-only-prerecorded)

---

### Accurate captions are available (CON-1-2)
Captions are available for content with both audio and video, except when the content is an alternative for text and is clearly labeled as such.

#### How to test
**Tool:** Visual inspection

1. Identify prerecorded content with both audio and video.
2. Confirm that captions are available.
3. Confirm the captions contain all audio information (for example: speech, sound effects, music, etc.).

#### Test outcomes
- **Pass**: All prerecorded content with both audio and video has accurate captions.

- **Fail**: Any prerecorded content with both audio and video does not have captions, or the captions do not contain all audio information.

- **NA**: No prerecorded content with both audio and video exists.

#### Related WCAG criteria
[WCAG 2.2 A - 1.2.2 Captions (Prerecorded)](https://www.w3.org/TR/WCAG22/#captions-prerecorded)

---

### Audio description or media alternative (prerecorded) (CON-1-3)
A transcript or audio description is available for content with both audio and video, except when the content is an alternative for text and is clearly labeled as such.

**Note:** If all of the information in the video track is provided in the audio track, no audio description is needed.

#### How to test
**Tool:** Visual inspection

1. Test “Audio Description (Prerecorded)”.
2. If "Audio Description (Prerecorded)" passes, this also passes.
3. If "Audio Description (Prerecorded)" fails, confirm a transcript exists that describes the meaningful visual information.

#### Test outcomes
- **Pass**: "Audio Description (Prerecorded)" is passing -or- a transcript is available that describes all meaningful information.

- **Fail**: Neither a transcript or audio description is available and there is meaningful information not described by the audio.

- **NA**: No content with both audio and video exists.
-or- the exception is met

#### Related WCAG criteria
[WCAG 2.2 A - 1.2.3 Audio Description or Media Alternative (Prerecorded)](https://www.w3.org/TR/WCAG22/#audio-description-or-media-alternative-prerecorded)

---

### Audio description (prerecorded) (CON-1-4)
An audio description track must be available if there is meaningful visual information that is not included in the audio track for prerecorded content with both audio and video.

**Note:** If all of the information in the video track is provided in the audio track, no audio description is needed.

#### How to test
**Tool:** Visual inspection

1. Identify prerecorded content with both audio and video.
2. If the content provides meaningful visual information that is not described by the audio, confirm it also includes an audio description track that explains the visual information.

#### Test outcomes
- **Pass**: Audio description is available when needed.

- **Fail**: Meaningful visual information in the video is not described by the audio and an audio description track is missing, incomplete, or inaccurate.

- **NA**: The audio describes the visual content -or- there is no prerecorded content with both audio and video.

#### Related WCAG criteria
[WCAG 2.2 AA - 1.2.5 Audio Description (Prerecorded)](https://www.w3.org/TR/WCAG22/#audio-description-prerecorded)

---

### Pause or adjust volume for auto playing audio (CON-1-5)
For any audio which 1) plays automatically and 2) lasts for >3 seconds, one of the following must be true:

- A mechanism to pause the content is presented to the user
-or-
- A mechanism for adjusting the volume of the content is presented to the user and it does not rely on the system audio levels to adjust the volume.

#### How to test
**Tool:** Visual inspection

Confirm that for any audio which plays automatically and lasts for >3 seconds, one of the following is true:
- A mechanism to pause the content is presented to the user.
-or-
- A mechanism for adjusting the volume of the content is presented to the user and it does not rely on the system audio levels to adjust the volume.

#### Test outcomes
- **Pass**: For all content which plays automatically and lasts for more than 3 seconds a mechanism is provided to pause or adjust volume.

- **Fail**: A mechanism is not provided to pause or adjust volume for all content which plays automatically and lasts for more than 3 seconds.

- **NA**: No content which plays automatically and lasts for more than 3 seconds is present.

#### Related WCAG criteria
[WCAG 2.2 A - 1.4.2 Audio Control](https://www.w3.org/TR/WCAG22/#audio-control)

---

### Pause, stop, hide moving content (CON-1-6)
A mechanism must be provided to pause, stop, or hide any content that meets the following criteria:
- Starts automatically
- Is presented in parallel with other content
-and-
- moves, blinks or scrolls for >5 seconds
-or- 
- All auto-updating content regardless of duration

#### How to test
**Tool:** Visual inspection

Perform a visual inspection of the screen.

Confirm that for any content that meets the following criteria, a mechanism is provided to pause, play, or hide the applicable content:
- Starts automatically
- Is presented in parallel with other content
-and-
- moves, blinks or scrolls for >5 seconds
-or- 
- All auto-updating content regardless of the time of duration

#### Test outcomes
- **Pass**: A mechanism is provided to pause, stop, or hide auto-playing; moving or blinking; auto-updating content.

- **Fail**: A mechanism is not provided to pause, stop, or hide auto-playing; moving or blinking; auto-updating content.

- **NA**: No auto-playing; moving or blinking; auto-updating content is present.

#### Related WCAG criteria
[WCAG 2.2 A - 1.3.3 Sensory Characteristics](https://www.w3.org/TR/WCAG22/#sensory-characteristics)

---

## Text and copy (CON-2)

### Instructions don't rely on sensory cues (CON-2-1)
Instructions must never refer solely to sensory cues such as size, shape, color, sound, or spatial directions.

**Note:** When instructions refer to an interactive element, use the programmatic name of the element.

#### How to test
**Tool:** Visual inspection

1. Review any instruction text (on-screen and screen reader only).
2. Confirm that Instructions and interactions never refer solely to sensory cues such as size, shape, color, sound, or spatial directions.

#### Test outcomes
- **Pass**: Instructions and interactions never refer solely to sensory cues such as size, shape, color, sound, or spatial directions.

- **Fail**: Instructions and interactions refer solely to sensory cues such as size, shape, color, sound, or spatial directions.

- **NA**: No instructions are present.

#### Related WCAG criteria
[WCAG 2.2 A - 1.3.3 Sensory Characteristics](https://www.w3.org/TR/WCAG22/#sensory-characteristics)

---

### Visible and programmatic label consistency (CON-2-2)
If a control's visual label differs from the programmatic/accessible name value, then the programmatic/accessible name value includes the visual label.

#### How to test
**Tool:** VoiceOver (iOS), TalkBack (Android)

1. Locate all labels on input fields and interactive components.
2. Note the label presented visually in the user interface.
3. Note the programmatic (accessibility) label using either TalkBack or VoiceOver.
4. Confirm that the accessibility label includes the same text as the visual label .

#### Test outcomes
- **Pass**: All controls which have a different programmatic/accessible name value and visual label have the visual label text within the programmatic/accessible name value text string.

- **Fail**: One or more control which has a different programmatic/accessible name value and visual label does not have the visual label text within the programmatic/accessible name value text string.

- **NA**: No controls which have a different programmatic/accessible name value and visual label are present.

#### Related WCAG criteria
[WCAG 2.2 A - 2.5.3 Label in Name](https://www.w3.org/TR/WCAG22/#link-purpose-in-context)

---

### Link text in context (CON-2-3)
Link text MUST describe the destination or purpose of every link in a way that makes the destination or purpose clear to all users in context with the surrounding content

#### How to test
**Tool:** VoiceOver (iOS), TalkBack (Android) screen reader

1. Access all link text using a screen reader.
2. Determine whether someone can understand where the link will take them based on the link name, surrounding content, and any additional programmatic context provided (for example: accessibility label).

#### Test outcomes
- **Pass**: All link text effectively describes the destination.

- **Fail**: Some link text does not effectively describe the destination.

- **NA**: No links are present.

#### Related WCAG criteria
[WCAG 2.2 A - 2.4.4 Link Purpose (In Context)](https://www.w3.org/TR/WCAG22/#link-purpose-in-context)

---

### Language of parts (CON-2-4)
Any content presented in a language other than the default application language is read appropriately by the screen reader.

#### How to test
**Tool:** VoiceOver (iOS), TalkBack (Android) screen reader

1. Use a screen reader to interact with any application content presented in a language other than the defaul application language.
2. Ensure that the screen reader output matches the correct language.

#### Test outcomes
- **Pass**: Any content presented in a language other than the default language is read appropriately by the screen reader.

- **Fail**: Some or all content presented in a language other than the defaul language is not read appropriately by the screen reader.

- **NA**: No content is presented in a language other than the default application language.

#### Related WCAG criteria
[WCAG 2.2 A - 3.1.2 Language of Parts](https://www.w3.org/TR/WCAG21/#headings-and-labels)

---

### Use headings (CON-2-5)
All text that functions as a heading is read by a screen reader as a heading and uses the correct heading level

#### How to test
**Tool:** VoiceOver (iOS), TalkBack (Android) screen reader

1. Change the navigation mode to headings.
2. Confirm all headings are reached using heading navigation.
3. Confirm correct heading level is used.

#### Test outcomes
- **Pass**: All headings are reached using heading navigation and are at the correct level.

- **Fail**: Some headings are not reached using heading navigation or use an incorrect level.

- **NA**: No headings are present.

#### Related WCAG criteria
[WCAG 2.2 A - 1.3.1 Info and Relationships](https://www.w3.org/TR/WCAG22/#info-and-relationships)

---

### Headings and labels (CON-2-6)
Headings and labels must accurately describe their content or interactive component

#### How to test
**Tool:** Visual inspection

1. Review all content that serves as a heading for a group of conten.
2. Confirm that each heading makes sense as the heading for the grouped content beneath it.
3. Locate all labels on interactive components.
4. Confirm that all labels on interactive components accurately describe the control's purpose.

#### Test outcomes
- **Pass**: Headings and labels accurately describe their content and/or interactive component.

- **Fail**: One or more headings and/or labels do not accurately describe their content and/or interactive component.

- **NA**: No headings or labels are present.

#### Related WCAG criteria
[WCAG 2.2 AA - 2.4.6 Headings and Labels](https://www.w3.org/TR/WCAG22/#headings-and-labels)

</Breakless>

---

# index

---
title: Interaction
side_nav_title: Interaction
description: Find interaction requirements for testing mobile experiences.
side_nav_aria_label: Interaction requirements for mobile.
side_nav_order: 2

---

<Breakless>

## Layout (INT-1)

### Content reflow (INT-1-1) 
Content must support reflow without requiring two-dimensional scrolling (except when the content requires a two-dimensional layout for meaning like tables, maps, or diagrams)

#### How to test
**Tool:** Visual inspection

1. Increase display zoom using OS level settings:
    - iOS: Settings > Display & Brightness > Display Zoom > Larger Text.
    - Android: Settings > Display > Screen Zoom, set to maximum.
2. Confirm that all content is available without requiring two-dimensional scrolling.

#### Test outcomes
- **Pass**: There is not a loss of information, meaning, or functionality and only one scroll dimension is required.

- **Fail**: There is a loss of information, meaning, or functionality OR vertical and horizontal scrolling are required to view the content.

- **NA**: Content is any of the following:
    - Data tables
    - Photos
    - Maps
    - Charts
    - Games
    - UI with toolbars

#### Related WCAG criteria
[WCAG 2.2 AA - 1.4.10 Reflow](https://www.w3.org/TR/WCAG21/#info-and-relationships)

---

### Consistent help (INT-1-2)
If a view includes the help options listed below, they are in the same location on similar views:
- Human contact details
- Human contact mechanism
- Self-help option
- A fully automated contact mechanism

#### How to test
**Tool:** Visual inspection

1. Locate if any of the listed help options in exist in the view:
    - Human contact details;
    - Human contact mechanism;
    - Self-help option;
    - A fully automated contact mechanism.
2. Determine if the help is in the same location across similar views.

#### Test outcomes
- **Pass**: Help across similar views is in the same location.

- **Fail**: Help across similar views is not in the same location.

- **NA**: No help options exist in the view.

#### Related WCAG criteria
[WCAG 2.2 A - 3.2.6 Consistent Help](https://www.w3.org/TR/WCAG22/#consistent-help)

---

## Forms (INT-2)

### Group fields and controls (INT-2-1)
When controls are related/grouped together this grouping should be clearly presented to assistive technology.

#### How to test
**Tool:** VoiceOver (iOS), TalkBack (Android)

1. Locate any input fields and interactive controls that are related and share a grouping relationship (note: this may be apparent visually or it may just be implied).
2. Confirm that the grouping relationship is communicated by the screen reader.

#### Test outcomes
- **Pass**: All control and input field grouping is communicated by the screen reader.

- **Fail**: One or more control/input field grouping is not communicated by the screen reader.

- **NA**: No control/input field groupings are present.

#### Related WCAG criteria
[WCAG 2.2 A - 1.3.1 Info and Relationships](https://www.w3.org/TR/WCAG22/#info-and-relationships)

---

### Required fields (INT-2-2)
Required fields must be noted and communicated visually through more than color alone, and communicated to assistive technology

#### How to test
**Tool:** Visual inspection and screen reader

1. Locate any required fields or controls.
2. Confirm that there is a visual indication of each field that is required that is not presented through color alone.
3. Confirm that the required fields are communicated programmatically to screen reader users.

#### Test outcomes
- **Pass**: All required fields are noted visually through more than color alone and communicated to assistive technology.

- **Fail**: One or more required fields are not noted visually through more than color alone or communicated to assistive technology.

- **NA**: Required fields are not present.

#### Related WCAG criteria
[WCAG 2.2 A - 1.3.1 Info and Relationships](https://www.w3.org/TR/WCAG22/#info-and-relationships)

---

### Check for errors (INT-2-3)
If an input error is automatically detected, the item that is in error is identified and the error is described to the user in text.

#### How to test
**Tool:** Visual inspection

1. Identify any inputs that have automatic validation.
2. For each input, verify that errors are described in text.

#### Test outcomes
- **Pass**: Errors are identified and the errors are described to the user in text.

- **Fail**: Errors are identified but the errors are not described to the user in text.

- **NA**: There are no inputs with automatic validation.

#### Related WCAG criteria
[WCAG 2.2 A - 3.3.1 Error Identification](https://www.w3.org/TR/WCAG22/#error-identification)

---

### Highlight in-line errors visually (INT-2-4)
When an error is detected using in-line validation, highlight the field (for example: with a bold red border, error icon with proper alternative text) and place error helper text near it.

#### How to test
**Tool:** Visual inspection

1. Identify any inputs that have automatic validation.
2. Confirm that when an error is detected using in-line validation, the field is highlighted.

#### Test outcomes
- **Pass**: When an error is detected using in-line validation, the visual UI highlights the field and places error helper text near it.

- **Fail**: For one or more client-side validated forms when an error is detected using client side validation, the visual UI does not highlight the field or place error helper text near it.

- **NA**: No forms are present.

#### Related WCAG criteria
[WCAG 2.2 A - 3.3.1 Error Identification](https://www.w3.org/TR/WCAG22/#error-identification)

---

### Summary before submit (INT-2-5)
If user input is collected across multiple pages in order to execute a transaction of some kind the user must be presented with a summary of the input before submitting. The user must be able to change input prior to final submission after reviewing.

#### How to test
**Tool:** Visual inspection

1. Identify any workflows which gather input from the user and conclude with a submit action (for example: sign up, checkout, transactions, or capture of personal information).
2. Confirm that there is a step available to the user for reviewing the information prior to the final submit.
3. Confirm that the user can easily make corrections or changes to the information prior to submit.

#### Test outcomes
- **Pass**: A summary of user input is provided prior to final submit AND the user can edit or make corrections as needed.

- **Fail**: A summary of user input is not provided prior to final submit OR the user cannot edit or make corrections as needed.

- **NA**: User input is not collected across pages to execute a transaction.

#### Related WCAG criteria
[WCAG 2.2 AA - 3.3.4 Error Prevention (Legal, Financial, Data)](https://www.w3.org/TR/WCAG22/#error-prevention-legal-financial-data)

---

### Error suggestion (INT-2-6)
When errors are detected, suggestions are provided to correct them, unless it would jeopardize the security or purpose of the content.

#### How to test
**Tool:** Visual inspection

1. Locate any errors that can appear.
2. Trigger each error.
3. Confirm that, when possible, an error message describes how to correct the error (eg "username field is required" or "phone number must contain 10 digits").

#### Test outcomes
- **Pass**: Suggestions to fix errors are present.

- **Fail**: One or more errors exist but users are not informed how to fix the errors.

- **NA**: No errors exist.

#### Related WCAG criteria
[WCAG 2.2 AA - 3.3.3 Error Suggestion](https://www.w3.org/TR/WCAG22/#error-suggestion)

---

### Redundant entry (INT-2-7)
If a view is contained within a process then information provided on the first step of the process is auto-filled in the next steps unless the information is required for security.

#### How to test
**Tool:** Visual inspection

1. Inspect the view to determine if it is a step in a process.
2. If information is provided in an earlier step in this process, confirm that this information is auto-filled in later steps.

#### Test outcomes
- **Pass**: Information provided during the process will autofill if later steps require the same information.

- **Fail**: Fields do not autofill when the same information has been provided on previous steps.

- **NA**: The view does not contain any process-based functionality or information reentry is essential or required for security.

#### Related WCAG criteria
[WCAG 2.2 A - 3.3.7 Redundant Entry](https://www.w3.org/TR/WCAG22/#redundant-entry)

---

## Widgets and controls (INT-3)

### Gestures (INT-3-1)
Widgets and controls can be operated via a single pointer with a gesture that does not require a specific path, unless a multi-pointer or path-based gesture is essential to the function of the control.

#### How to test
**Tool:** Visual inspection

1. Identify any controls that are operated via a multi-point OR path-based interaction in the application.
2. Confirm that the same actions can be performed through a single pointer method that does not require a specific path.

#### Test outcomes
- **Pass**: All controls that are operated via a multi-point OR path-based interaction can also be operated through a single pointer method that does not require a specific path.

- **Fail**: There are controls that require multi-pointer interaction OR they require a specific path-based gesture where it is not essential to the function of the control.

- **NA**: No custom gesture control is present OR the multi-pointer or path-based gesture is essential to the function of the control.

#### Related WCAG criteria
[WCAG 2.2 A - 2.5.1 Pointer Gestures](https://www.w3.org/TR/WCAG22/#pointer-gestures)

---

### Name (INT-3-2)
All interactive elements must have a programmatic name accessible to assistive technology

#### How to test
**Tool:** VoiceOver (iOS), TalkBack (Android)

1. Review each interactive element with a screen reader.
2. For each interactive element, verify the screen reader announces the name of the element.

#### Test outcomes
- **Pass**: All interactive elements have a name announced by the screen reader.

- **Fail**: One or more interactive elements do not have a name announced by the screen reader.

#### Related WCAG criteria
[WCAG 2.2 A - 4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value)

---

### Role (INT-3-3)
All elements with semantic meaning have a valid, accurate programmatic role accessible to assistive technology

#### How to test
**Tool:** VoiceOver (iOS), TalkBack (Android)

1. Locate all elements in the view with semantic meaning. (for example: headings, buttons and links, dialogs, etc…).
2. For each element with semantic meaning, verify the screen reader announces the role of the element. 
3. Verify that the role announced for the element is valid and matches the semantic meaning of the element (for example: a link announces a link role, a button announces a button role, etc.).

#### Test outcomes
- **Pass**: All elements with semantic meaning have a role announced by the screen reader that matches the semantic meaning of the element.

- **Fail**: One or more semantic elements do not have a role announced by the screen reader or the role announced does not match the semantic meaning of the element.

#### Related WCAG criteria
[WCAG 2.2 A - 4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value)

---

### Value, states, properties (INT-3-4)
States, properties, and values of elements are programmatically available to assistive technology, Any changes to these items are also communicated to assistive technology.

#### How to test
**Tool:** VoiceOver (iOS), TalkBack (Android)

1. Locate all elements in the view which have states, properties, and/or values associated (for example: pressed/invalid state, an error message property on an invalid input, a user-input text string value in a "name" text field, etc…).
2. For each identified state, property, or value, confirm that the screen reader announces it when interacting with the associated element.
**Note:** If a state, property, or value has changed, the screen reader can determine the change.

#### Test outcomes
- **Pass**: All states, properties, and values are announced by the screen reader when interacting with the associated element.

- **Fail**: One or more states, properties, or values are not announced to the screen reader when interacting with the associated element.

- **NA**: No elements with states, properties, or values are present.

#### Related WCAG criteria
[WCAG 2.2 A - 4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value)

---

### Name consistently (INT-3-5)
UI controls with the same purpose need to be identified with the same label for consistency

#### How to test
**Tool:** Visual inspection and screen reader

1. Determine whether there are any duplicate UI controls with the same purpose.
2. Confirm that they are consistently identified with the same label visually and to screen reader users.

#### Test outcomes
- **Pass**: All UI controls with the same purpose are consistently identified with the same label visually and to screen reader users.

- **Fail**: One or more UI controls with the same purpose are not consistently identified with the same label visually and to screen reader users.

- **NA**: No duplicate UI controls with the same purpose are present.

#### Related WCAG criteria
[3.2.4 Consistent Identification](https://www.w3.org/TR/WCAG21/#consistent-identification)

---

### On focus (INT-3-6)
Changes of context do not occur when focus (keyboard, screen reader, switch) moves to controls 

#### How to test
**Tool:** Keyboard and screen reader

1. Place focus (keyboard, screen reader) on each interactive control and input field.
2. Interact with each control and input field.
3. Confirm that no changes of context result from moving focus to a control.

#### Test outcomes
- **Pass**: No changes of context result from an on focus.

- **Fail**: A change of context results from an on focus.

#### Related WCAG criteria
[WCAG 2.2 A - 3.2.1 On Focus](https://www.w3.org/TR/WCAG22/#on-focus)

---

### On input (INT-3-7)
Changing the value of any interactive element does not automatically cause a change of context unless the user has been advised beforehand.

#### How to test
**Tool:** Visual inspection

1. Locate any elements in the view that has a value that can be updated (for example: checkboxes, radio buttons, selects, etc.).
2. Change the value for each element.
3. Confirm that unexpected changes do not occur.

#### Test outcomes
- **Pass**: No changes of context occur on value change or the user is advised beforehand.

- **Fail**: One or more changes of context occur on value change and the user is not advised beforehand.

- **NA**: No interactive elements can accept a value change.

#### Related WCAG criteria
[WCAG 2.2 A - 3.2.2 On Input](https://www.w3.org/TR/WCAG22/#on-input)

---

### Same relative order (INT-3-8)
Components, like links, buttons, or contact forms, that appear on multiple views must appear in the same relative order on every view.

#### How to test
**Tool:** Visual inspection

1. Perform a visual inspection of the view looking for navigation components.
2. Confirm that components (links, buttons, contact forms, etc.) that appear on multiple views appear in the same relative order on every view.

#### Test outcomes
- **Pass**: Components that appear on multiple views appear in the same relative order on every view.

- **Fail**: One or more component that appears on multiple views does not appear in the same relative order on every view.

- **NA**: No component appears on multiple views.

#### Related WCAG criteria
[WCAG 2.2 AA - 3.2.3 Consistent Navigation](https://www.w3.org/TR/WCAG22/#consistent-navigation)

---

### Touch cancellation (INT-3-9)
Actions completed with a touch input MUST NOT use the down-event to execute any part of the function.
-OR-
Make sure there is a way for the user to abort or undo the action.
-OR-
Allow the up-event to reverse any outcome of the preceding down-event

#### How to test
**Tool:** Visual inspection

Confirm that there are no actions which are completed using the down-event from touch input OR that there is a way for the user to abort or undo the action OR that the up-event allows the user to reverse any outcome of the preceding down-event.

#### Test outcomes
- **Pass**: No actions are completed using the down event OR there is a way to abort or undo an action completed on the down-event OR the up-event allows the reversal of the preceding down-event.

- **Fail**: Actions are completed using the down event AND there is not a way to abort or undo the action AND the up-event does not allow reversal of the preceding down-event.

#### Related WCAG criteria
[WCAG 2.2 A - 2.5.2 Pointer Cancellation](https://www.w3.org/TR/WCAG22/#pointer-cancellation)

---

### Dragging movements (INT-3-10)
An action that relies on dragging of content can also be achieved by a single pointer without dragging unless dragging is essential to the activity.

Example of single pointer Pass: A quiz relies on users tapping and dragging information into the correct bucket. Users are also able to tap once to select an option, then tap on the correct bucket.
Example of essential activity: A medical app requires tapping and dragging an object to a target to accurately measure the user’s precision.

#### How to test
**Tool:** Visual inspection

1. Inspect the view to determine whether any functionality requires a dragging movement to access content.
2. For any dragging content, confirm that it can be used with a single pointer without dragging.

#### Test outcomes
- **Pass**: All drag functionality can also be performed with a single pointer OR the dragging movement is essential.

- **Fail**: Drag functionality cannot be completed with a single pointer.

- **NA**: The view does not contain drag functionality.

#### Related WCAG criteria
[WCAG 2.2 AA - 2.5.7 Dragging Movements](https://www.w3.org/TR/WCAG22/#dragging-movements)

---

## Notifications and alerts (INT-4)

### Notifications, status messages, etc. (INT-4-1) 
When the app sends the user info in a status update or notification it needs to be announced to screen readers without user placing focus there

#### How to test
**Tool:** VoiceOver (iOS) TalkBack (Android)

1. Interact with all notification and status message content using a screen reader.
2. When the app sends the user info in a status update or notification, confirm that it is announced to the screen reader without the user placing focus there and announced correctly.

#### Test outcomes
- **Pass**: All notifications or status messages are shown to the screen reader and announced correctly.

- **Fail**: One or more notifications or status messages is not shown to the screen reader and announced correctly.

- **NA**: No notifications or status messages occur.

#### Related WCAG criteria
[WCAG 2.2 AA - 4.1.3 Status Messages](https://www.w3.org/TR/WCAG22/#status-messages)

---

## Keyboard compatibility (INT-5)

### Focus order (INT-5-1) 
When someone navigates using a keyboard or other sequential nav device the focus order is logical

#### How to test
**Tool:** Keyboard

1. Use a keyboard to control the mobile device.
2. Confirm that when someone navigates using a keyboard or other sequential nav device the order they are taken through the UI preserves meaning and operability.

#### Test outcomes
- **Pass**: Focus order is logical.

- **Fail**: Focus order is not logical.

#### Related WCAG criteria
[WCAG 2.2 A - 2.4.3 Focus Order](https://www.w3.org/TR/WCAG22/#focus-order)

---

### Visible keyboard focus (INT-5-2)
When a keyboard or any other sequential navigation device is used there is a visible indication of focus that is always on the correct element

#### How to test
**Tool:** Screen reader AND keyboard

1. Use a keyboard to control the mobile device.
2. Confirm that when a keyboard is used, there is a visible indication of focus that is always on the correct element.

#### Test outcomes
- **Pass**: Focus is always visible and in the correct place.

- **Fail**: Focus is not always visible or occurs in the wrong location.

#### Related WCAG criteria
[WCAG 2.2 AA - 2.4.7 Focus Visible](https://www.w3.org/TR/WCAG22/#focus-visible)

---

### Keyboard support (INT-5-3)
All functionality and content must be available to users via keyboard only, without requiring specific timing of keystrokes

#### How to test
**Tool:** Keyboard

1. Use a bluetooth keyboard to control the mobile device.
2. Confirm that everything in the app can be performed with a keyboard alone (without the touch screen).

#### Test outcomes
- **Pass**: All features and functionality of the app are keyboard only compatible.

- **Fail**: One or more features or functionality is not keyboard only compatible.

#### Related WCAG criteria
[WCAG 2.2 A - 2.1.1 Keyboard](https://www.w3.org/TR/WCAG22/#keyboard)

---

### No keyboard trap (INT-5-4)
Keyboard focus must not become stuck when navigating through content.

#### How to test
**Tool:** Keyboard

Run through all use cases using keyboard and confirm that when focus is moved to an interactive element, that focus can also be moved away from the element.

#### Test outcomes
- **Pass**: Focus can move through the content without getting stuck.

- **Fail**: Focus cannot move through the content without getting stuck.

#### Related WCAG criteria
[WCAG 2.2 A - 2.1.2 No Keyboard Trap](https://www.w3.org/TR/WCAG22/#no-keyboard-trap)

---

### Focus not obscured (INT-5-5)
When a focusable element has keyboard focus, the element is at least partially visible.

#### How to test
**Tool:** Keyboard

1. Tab through everything in the view.
2. For each focusable element, when it has focus, confirm at least part of the element is visible (not fully obscured by other content or off the screen).
**Note:** If content can be repositioned by the user, only test the initial position.

#### Test outcomes
- **Pass**: Focusable elements are at least partially visible when focused.

- **Fail**: One or more focusable elements are fully obscured when focused.

#### Related WCAG criteria
[WCAG 2.2 AA - 2.4.11 Focus Not Obscured](https://www.w3.org/TR/WCAG22/#focus-not-obscured-minimum)

---

### Single character keyboard shortcuts (INT-5-6)
If a single character shortcut is used then users must have the option to either turn it off or remap it to one or more non-printable keyboard characters.
-or-
Make sure the single character shortcut is only active when the component it affects has focus.

#### How to test
**Tool:** Keyboard

Confirm that where a single character shortcut is used that users have the option to either turn it off or remap it to one or more non-printable keyboard characters or make sure the single character shortcut is only active when the component it affects has focus.

#### Test outcomes
- **Pass**: For all single character shortcuts, users have the option to either turn off or remap it to one or more non-printable keyboard characters or the single character shortcut is only active when the component it affects has focus.

- **Fail**: For all single character shortcuts, users do not have the option to either turn off or remap it to one or more non-printable keyboard characters and the single character shortcut is active at all times.

- **NA**: No single character shortcuts are present.

#### Related WCAG criteria
[WCAG 2.2 A - 2.1.4 Character Key Shortcuts](https://www.w3.org/TR/WCAG22/#character-key-shortcuts)

</Breakless>


---

# index

---
title: Visual
side_nav_title: Visual
description: Find visual requirements for testing mobile experiences.
side_nav_aria_label: Visual requirements for mobile.
side_nav_order: 3

---

<Breakless>

## Color and contrast (VIS-1)

### Not only color (VIS-1-1) 
Color is not the only way that meaning or information is conveyed visually

#### How to test
**Tool:** Visual inspection

1. Identify any content which relies on color to convey meaning or information.
2. Determine whether or not the same meaning or information is provided when color is changed to grayscale.
3. Confirm that something other than color is provided to provide the same meaning or information when color is removed.

#### Test outcomes
- **Pass**: All content that uses color to convey meaning or information also includes a non-color equivalent.

- **Fail**: Some content that uses color to convey meaning or information does not include a non-color equivalent.

- **NA**: Color is not used to convey meaning or information.

#### Related WCAG criteria
[WCAG 2.2 A - 1.4.1 Use of Color](https://www.w3.org/TR/WCAG22/#use-of-color)

---

### Color contrast ratio (VIS-1-2)
A color contrast ratio of text and images of text to their backgrounds must be at least 4.5:1, except if the text is 18pt or 14pt bold or larger, where a ratio of 3:1 is then required.

#### How to test
**Tool:** Contrast Checking Tool such as WebAIM Contrast Checker

1. Determine the color used for the foreground and background on all text content.
2. Enter the values in a color contrast tool such as WebAIM Contrast Checker.
3. Confirm that text has sufficient contrast against its background and/or compared to surrounding elements.
**Note:** If using a physical mobile device, you may need to take a screenshot to verify contrast ratio on a desktop or know the color values.

#### Test outcomes
- **Pass**: All text content has sufficient contrast.

- **Fail**: Some text content does not have sufficient contrast.

#### Related WCAG criteria
[WCAG 2.2 AA - 1.4.3 Contrast (Minimum)](https://www.w3.org/TR/WCAG22/#contrast-minimum)

---

### Contrast for non-text UI components (VIS-1-3)
All non-text content and controls have sufficient contrast ratio of 3:1 against their respective background. This includes both graphical content (for example: iconography) as well as interactive content and can also include a combination of both.

#### How to test
**Tool:** Contrast Checking Tool such as WebAIM Contrast Checker

1. Determine the color used for the foreground and background on all non-text elements .
2. Enter the values in a color contrast tool.
3. Confirm that each interactive element has at least 3:1 contrast against its background and/or compared to surrounding elements.
**Note:** If using a physical mobile device, you may need to take a screenshot to verify contrast ratio on a desktop or know the color values.

#### Test outcomes
- **Pass**: All non-text content has sufficient contrast.

- **Fail**: Some non-text content does not have sufficient contrast.

- **NA**: A non-text element that is in a disabled state and other similar criteria may result in NA for a specific non-text element (view requirement for details).

#### Related WCAG criteria
[WCAG 2.2 AA - 1.4.11 Non-text Contrast](https://www.w3.org/TR/WCAG22/#non-text-contrast)

---

## Size and layout (VIS-2)

### Touch target size (VIS-2-1) 
Touch targets need to be large enough - Android 48x48dp minimum, iOS 44x44pt minimum

#### How to test
**Tool:** Xcode - Accessibility Inspector (iOS), Accessibility Scanner (Android)

1. Target each interactive element that will receive touch interaction or input.
2. Determine the size of the touch element's target area.
3. Confirm that the size of the touch element's target area is at least 44x44pt for iOS and 48x48dp for Android.

#### Test outcomes
- **Pass**: All touch target areas are at least 44x44pt for iOS and 48x48dp for Android.

- **Fail**: One or more touch target areas are less than 44x44pt for iOS and 48x48dp for Android.

- **NA**: Target is a link or button in a block of text that requires a specific presentation.

#### Related WCAG criteria
[WCAG 2.2 AA - 2.5.8 Target Size](https://www.w3.org/TR/WCAG22/#target-size-minimum)

---

### Code order matches logical content order (VIS-2-2)
The reading order matches the visual order of content

#### How to test
**Tool:** Visual inspection and screen reader

1. Evaluate the visual content order and compare to the order of presentation when using a screen reader.
2. Verify the reading order matches the visual order of content.

#### Test outcomes
- **Pass**: The visual content order is consistent for screen reader users also.

- **Fail**: The visual content order and screen reader content order do not match.

#### Related WCAG criteria
[WCAG 2.2 A - 1.3.2 Meaningful Sequence](https://www.w3.org/TR/WCAG22/#meaningful-sequence)

---

### No blinking or flashing (VIS-2-3)
No Blinking or Flashing (VIS-2-3)
Content that blinks or flashes rapidly must never be used.
"Rapidly" means blinking/flashing more than 3 times in 1 second. If there is any doubt about the frequency of flashing then this would fail.

#### How to test
**Tool:** Visual inspection

1. Perform a visual inspection of the view.
2. Confirm that each view contains no content that blinks or flashes rapidly.

#### Test outcomes
- **Pass**: Content that blinks or flashes rapidly is not used.

- **Fail**: Content that blinks or flashes rapidly is used.

#### Related WCAG criteria
[WCAG 2.2 A - 2.3.1 Three Flashes or Below Threshold](https://www.w3.org/TR/WCAG22/#three-flashes-or-below-threshold)

---

## Images and graphics (VIS-3)

### Text alternatives (VIS-3-1)
All meaningful non-text content MUST provide text alternatives that provide equivalent information, context, and purpose to the user AND all decorative content is hidden from the user.

#### How to test
**Tool:** VoiceOver (iOS), TalkBack (Android)

1. Evaluate all non-text content using VoiceOver/Talkback.
2. Confirm that all non-text content provides text alternatives that provide equivalent information, context, and purpose to the user AND that decorative non-text content is hidden.

#### Test outcomes
- **Pass**: All images and non-text objects that need a text alternative have an accurate and descriptive accessibility label.

- **Fail**: One or more images or non-text objects that need a text alternative do not have an accessibility label OR the description is not accurate.

- **NA**: No images or non-text objects that need a text alternative are present.

#### Related WCAG criteria
[WCAG 2.2 A - 1.1.1 Non-text Content](https://www.w3.org/TR/WCAG22/#non-text-content)

---

### No images of text (VIS-3-2) 
Use real text instead of images of text to ensure that the text can be programmatically determined and adapts to user settings for zoom and color.

#### How to test
**Tool:** Screen reader or inspect app code

1. Identify images of text:
- Option 1: Move screen reader focus to all text content and listen for any instance where text is read as an image or focus does not move to the text.
- Option 2: Review the code for instances of images with text embedded in them.

#### Test outcomes
- **Pass**: All text content is real text.

- **Fail**: One or more images with embedded were found.

- **NA**: No images with embedded, meaningful text are present.

#### Related WCAG criteria
[WCAG 2.2 AA - 1.4.5 Images of Text](https://www.w3.org/TR/WCAG22/#images-of-text)

</Breakless>

---

# index

---
title: Annotations
side_nav_title: Annotations
description: Find annotation requirements for testing PDFs.
side_nav_order: 7
---

<Breakless>

## Annotations (PDF-8)

### Links and link text (PDF-8-1)
Link text in PDF documents is marked up in a way that is identifiable by keyboard and assistive technology users. Links in PDF documents should be represented by a Link tag and objects in its sub-tree, which includes a link object reference (or Link annotation) and one or more text objects. The text object(s) within the Link tag should be utilized by assistive technologies to provide a name for the link.

#### How to test
**Tool:** Screen reader

1. Use a screen reader to go through the PDF document. 
2. Verify that the link is read out properly and its description correctly indicates where the link leads to.
3. Verify the tag tree visually to ensure the links are correctly tagged as `<Link>` with a nested 'Link-OBJR' tag.
4. Use the Tab key to navigate to each link. Press Enter to verify that the link takes you to the intended target.

#### Test outcomes
- **Pass**: All links are accurately tagged, easily read by a screen reader, can be activated using a keyboard, and the link text clearly states the link's purpose.

- **Fail**: If any link is inaccurately tagged, cannot be read by a screen reader, can't be activated with a keyboard, or the link text does not clearly state the link's purpose.

- **NA**: There are no links present in the document.

#### Related WCAG criteria
- [WCAG 2.2 A - 2.4.4 Link Purpose (In Context)](https://www.w3.org/TR/WCAG22/#link-purpose-in-context)
- PDF-U/A - 7.18.5 Links

</Breakless>

---

# index

---
title: Document colors
side_nav_title: Document colors
description: Find document colors requirements for testing PDFs.
side_nav_order: 1
---

<Breakless>

## Document colors (PDF-2)

### Color contrast ratio (PDF-2-1)
The visual presentation of text and images of text has a contrast ratio of at least 4.5:1. However, if the text is 18pt or 14pt bold or larger, a lower ratio of 3:1 is acceptable.

#### How to test
**Tool:** WebAIM Color Contrast Checker

1. Use the CCA tool (or any similar tool) to analyze the color contrast ratio between text and its background, as well as images of text against their backgrounds.
2. Make sure the contrast ratio is at least 4.5:1. However, if the text is 18pt or 14pt bold or larger, a lower ratio of 3:1 is acceptable.

#### Test outcomes
- **Pass**: Text meets the required minimum contrast ratio.

- **Fail**: Text doesn't meet the minimum required contrast ratio.

- **NA**: Text is part of an inactive UI component or purely decorative.

#### Related WCAG criteria
- [WCAG 2.2 AA - 1.4.3 Contrast (Minimum)](https://www.w3.org/TR/WCAG22/#contrast-minimum)
- PDF-U/A-1 - 7.1 General

---

### Non-text contrast ratio (PDF-2-2)
All significant user interface elements and graphics have a contrast ratio of at least 3:1 against adjacent colors including the background and other non-text objects.

#### How to test
1. Use the CCA tool (or any similar tool) to analyze the color contrast ratio between all significant user interface elements and graphics against the background.
2. Verify that there is a contrast ratio of at least 3:1 against adjacent colors including the background and other non-text objects

#### Test outcomes
- **Pass**: All significant elements of the user interface and graphics maintain a 3:1 contrast ratio with surrounding colors.

- **Fail**: Important user interface elements or graphics don't maintain a 3:1 contrast ratio with the colors around them.

#### Related WCAG criteria
- [WCAG 2.1 AA - 1.4.11 Non-text Contrast](https://www.w3.org/TR/WCAG22/#non-text-contrast)
- PDF-U/A-1 - 7.1 General

---

### Not only color (PDF-2-3)
Color is not used as the only visual means of conveying information, indicating an action, prompting a response, or distinguishing a visual element.

#### How to test
1. Perform a visual inspection of the document.
2. Verify that whenever a difference in color is used to convey information, that information is also available in text or through some other alternative method.

#### Test outcomes
- **Pass**: A non-color alternative is presented along with color.

- **Fail**: Only color is used to indicate meaning.

- **NA**: Color is not used to convey meaning.

#### Related WCAG criteria
- [WCAG 2.2 A - 1.4.1 Use of Color](https://www.w3.org/TR/WCAG22/#use-of-color)
- PDF-U/A-1 - 7.1 General

</Breakless>

---

# index

---
title: Forms
side_nav_title: Forms
description: Find form requirements for testing PDFs.
side_nav_order: 8
---

<Breakless>

## Forms (PDF-9)

### Form controls (PDF-9-1)
A Widget annotation shall be nested within a Form tag. Widget annotations are used for interactive forms.

#### How to test
**Tool:** Adobe Acrobat Pro

1. Inspect the document for the presence of form fields.
2. Open the tags pane and review tags for all form fields.
3. Verify that they are correctly tagged using `<form>` with a nested 'Field name-OBJR' tag.
4. Verify that the `<form>` tag appears after and at the same level as the tag containing the visual text label of the field.

#### Test outcomes
- **Pass**: All form fields are tagged correctly using `<form>` with a nested 'Field name-OBJR' tag and appears after and at the same level as the tag containing the visual text label of the field.

- **Fail**: Any of the form controls do not have `<form>` tag with a nested 'Field name-OBJR' tag OR form tags do not appear after and at the same level as the tag containing the visual text label of the field.

- **NA**: Form fields/controls are not present.

#### Related WCAG criteria
PDF-U/A - 7.18.4 Forms

---

### Form tooltips (PDF-9-2)
Provide name, role, state, and value information for all form components to enable compatibility with assistive technology.

#### How to test
**Tool:** Adobe Acrobat Pro

1. Inspect the document for the presence of form fields.
2. Open the 'Prepare Form' tool and right-click on form fields to open the properties window.
3. Verify that each form field has accurate, descriptive, and unique tooltips.

#### Test outcomes
- **Pass**: All form fields have accurate, descriptive and unique tooltips.

- **Fail**: Any of the form controls do not have accurate, descriptive and unique tooltips.

- **NA**: Form fields/controls are not present.

#### Related WCAG criteria
- [WCAG 2.2 A - 4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value)
- PDF-U/A - 7.18.4 Forms

---

### Form radio buttons (PDF-9-3)
Make sure forms are accessible and usable by programmatically associating labels that convey the purpose of the fields.

#### How to test
**Tool:** Adobe Acrobat Pro

1. Navigate to the 'Tags' panel in Acrobat and find each radio button element.
2. Verify that visually grouped radio buttons share identical 'Name' and 'Title' attributes.
3. Verify that the radio button choice is correct for each option.

#### Test outcomes
- **Pass**: All radio buttons are accurately grouped, and each has the correct choice option text.

- **Fail**: Radio buttons are either not grouped accurately or their Choice option text is incorrect.

- **NA**: There are no radio buttons present.

#### Related WCAG criteria
- [WCAG 2.2 A - 4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value)
- PDF-U/A - 7.18.4 Forms

---

### Required form controls (PDF-9-4)
Notify the user when a field that must be completed has not been completed in a PDF form.

#### How to test
**Tool:** Adobe Acrobat Pro

1. Inspect the document for the presence of 'Required' form fields that need to be filled in.
2. Verify that visual form label includes the word ‘required’.
3. Open the 'Prepare Form' tool and right-click on form fields to open the properties window.
4. Verify that form's tooltip includes the word ‘required’.
5. Under the common properties, verify that "Required" check box is checked.

#### Test outcomes
- **Pass**: Each required form field includes the word 'required' in its visual label and tooltip. Additionally, the 'required' checkbox in properties is checked.

- **Fail**:Any required form field does not include the word 'required' in its visual label or tooltip, or the 'required' checkbox in properties is not checked.

- **NA**: Required Form fields/controls are not present.

#### Related WCAG criteria
- [WCAG 2.2 A - 3.3.1: Error Identification](https://www.w3.org/TR/WCAG22/#error-identification)
- [WCAG 2.2 A - 3.3.2: Labels or Instructions](https://www.w3.org/TR/WCAG22/#labels-or-instructions)
- PDF-U/A - 7.18.4 Forms

---

### Form input validation (PDF-9-5)
Notify the user when user input to a field that requires a specific, required format (for example: date fields) is not submitted in that format.

#### How to test
**Tool:** Adobe Acrobat Pro

1. Inspect the document for the presence of form fields with added input validations.
2. Verify that forms indicate when user input deviates from the required format and that the error messages are clear and accurate for all users including Assistive Technology users.

#### Test outcomes
- **Pass**: Error messages are clear and accurate for all users.

- **Fail**:Error messages are not clear or accurate for all users.

- **NA**: No Form fields/controls with input validations.

#### Related WCAG criteria
- [WCAG 2.2 A - 3.3.1: Error Identification](https://www.w3.org/TR/WCAG22/#error-identification)
- [WCAG 2.2 A - 3.3.2: Labels or Instructions](https://www.w3.org/TR/WCAG22/#labels-or-instructions)
- PDF-U/A - 7.18.4 Forms

---

### Target size (PDF-9-6)
Actionable components have a minimum target size of 24x24 CSS pixels except for:
 
- Objects with a target offset of at least 24px.
For example, a 20px width “Cancel” button has its right most edge at least 4px away from a “Submit” button placed on the right.
- Inline content within a sentence or block of text.
For example, a wiki paragraph has multiple instances of hyperlinked text. Increasing the height and width of these links would impact the presentation of text and make it more difficult to read.

#### How to test
**Tool:** Adobe Acrobat Pro

1. Inspect the document for the presence of form fields and controls.
2. Use the Adobe's 'Prepare Form' tool to find the height and width of a control.
3. Verify that each control has a width and height greater than or equal to 24px OR is less than 24px with sufficient spacing between controls (24px = .25in).
For example, a 20px width “Cancel” button has its right most edge at least 4px away from a “Submit” button placed on the right.

#### Test outcomes
- **Pass**: Both height and width are greater than or equal to 24px OR less than 24px with sufficient spacing between controls.

- **Fail**: Either the height or width is less than 24px AND the center of the control is less than 24px from another control.

- **NA**: Target is a link or button in a block of text that requires a specific presentation.

#### Related WCAG criteria
- [WCAG 2.2 AA - 2.5.8 Target Size (Minimum)](https://www.w3.org/TR/WCAG22/#target-size-minimum)
- PDF-U/A - 7.18.4 Forms

</Breakless>

---

# index

---
title: General
side_nav_title: General
description: Find general requirements for testing PDFs.
side_nav_aria_label: General requirements for PDF.
side_nav_order: 0

---

<Breakless>

## General (PDF-1)

### Use an automated testing tool (PDF-1-1)
When run against the page, the automated PDF Accessibility Checker validation tool MUST NOT report any errors.

#### How to test
**Tool:** Adobe Acrobat Pro/PDF Accessibility Checker

1. Execute the accessibility checker and analyze the results.
2. Verify that there are no issues to report (i.e, PDF/UA-1 compliant).

#### Test outcomes
- **Pass**: Issues are not reported by Accessibility Checker.

- **Fail**: Issues are reported by Accessibility Checker.

#### Related WCAG criteria
- [WCAG 2.2 - 4.1 Compatible](https://www.w3.org/TR/WCAG22/#compatible)
- PDF-U/A - 6 Conformance - requirements
- PDF-U/A - 7.1 General

---

### Document title (PDF-1-2)
The document has a title that describes topic or purpose and displays the document title in the title bar of a user agent.

#### How to test
1. Open the document in Adobe Acrobat Pro and navigate to File > Properties.
2. Verify that the document title is both correct and informative.
3. Select the 'Initial View' tab and verify that 'Document Title' is chosen in the 'Window Options' dropdown.

#### Test outcomes
- **Pass**: The document has a title that is relevant and explains its content, AND the initial view is set to 'Document Title'.

- **Fail**: The document lacks a title, OR the title is not relevant OR it doesn't explain its content, OR the initial view isn't set to 'Document Title'.

#### Related WCAG criteria
- [WCAG 2.2 A - 2.4.2 Page Titled](https://www.w3.org/TR/WCAG22/#page-titled)
- PDF-U/A - 7.1 General

</Breakless>

---

# index

---
title: Graphics
side_nav_title: Graphics
description: Find graphic requirements for testing PDFs.
side_nav_order: 3
---

<Breakless>

## Graphics (PDF-4)

### Text alternatives (PDF-4-1)
Provide text alternatives for images via an /Alt entry in the property list for a Tag.

#### How to test
**Tool:** Adobe Acrobat Pro

1. Inspect the document for all meaningful images.
2. Verify the alt text for every image and ensure they are accurate and descriptive.
3. Verify that the alternative text is less than 150 characters long.
4. For complex images, verify that they have elaborative text descriptions (ideally in a close proximity to the image) rather than long alternative text strings that are more than 150 characters.

#### Test outcomes
- **Pass**: All images have descriptive alt text shorter than 150 characters OR visible and elaborative text descriptions for complex images (for example: graphs).

- **Fail**: One or more images do not have alt text or visible elaborative text descriptions OR the alt text provided is not descriptive OR it is longer than 150 characters.

- **NA**: No images are present.

#### Related WCAG criteria
- [WCAG 2.2 A - 1.1.1 Non-text Content](https://www.w3.org/TR/WCAG22/#non-text-content)
- PDF-U/A-1 - 7.3 Graphics

---

### Decorative images (PDF-4-2)
Purely decorative images in PDF documents MUST be marked with /Artifact so that they can be ignored by Assistive Technology.

#### How to test
**Tool:** Adobe Acrobat Pro

1. Inspect the document for all decorative images.
2. Verify that every decorative image is appropriately marked as decorative or it is artifacted.

#### Test outcomes
- **Pass**: All non-text decorative content has been properly marked as decorative or artifacted.

- **Fail**: Non-text decorative content has NOT been labeled as an artifact.

- **NA**: There is no non-text decorative content present.

#### Related WCAG criteria
- [WCAG 2.2 A - 1.1.1 Non-text Content](https://www.w3.org/TR/WCAG22/#non-text-content)
- PDF-U/A-1 - 7.3 Graphics

---

### Images with captions (PDF-4-3)
A caption accompanying a figure shall be tagged with a Caption tag.

#### How to test
**Tool:** Adobe Acrobat Pro

1. Inspect the document for the presence of images with captions.
2. Verify that caption text is tagged as `<Caption>` and is a child element of the `<Figure>` tag that contains the actual image.

#### Test outcomes
- **Pass**: All the image captions are correctly tagged as `<caption>` and are child elements of the `<figure>` tag that contains the image.

- **Fail**: Any image caption is not tagged as `<caption>` or is not a child element of the `<figure>` tag that contains the image.

- **NA**: There are no images with captions are present.

#### Related WCAG criteria
- [WCAG 2.2 A - 1.1.1 Non-text Content](https://www.w3.org/TR/WCAG22/#non-text-content)
- PDF-U/A-1 - 7.3 Graphics

---

### No images of text (PDF-4-4)
Text is used to convey information rather than images of text except logos and instances where text within images is unavoidable, such as in graphs or screenshots.

#### How to test
**Tool:** Adobe Acrobat Pro

1. Inspect the document for images that contain text.
2. Verify that information is conveyed using actual text instead of images that contain text (the only exceptions are logos and instances where text within images is unavoidable, such as in graphs or screenshots).

#### Test outcomes
- **Pass**: Images of text are not used.

- **Fail**: Images of text are used.

- **NA**: There are no images of the text present OR the images are exempt from the requirement.

#### Related WCAG criteria
- [WCAG 2.2 A - 1.1.1 Non-text Content](https://www.w3.org/TR/WCAG22/#non-text-content)
- PDF-U/A-1 - 7.3 Graphics

</Breakless>

---

# index

---
title: Media content
side_nav_title: Media content
description: Find media content requirements for testing PDFs.
side_nav_order: 9
---

<Breakless>

## Media content (PDF-10)

### No blinking or flashing content (PDF-10-1)
Content that blinks or flashes MUST never be used.

#### How to test
**Tool:** Adobe Acrobat Pro

1. Open the document in Adobe Acrobat Pro and visually inspect the pages.
2. Confirm that no page contains content that flickers, blinks or flashes, either as effects controlled by JavaScript or as part of any videos embedded within the PDF.

#### Test outcomes
- **Pass**: Content that blinks or flashes is not used.

- **Fail**: Content that blinks or flashes is used.

#### Related WCAG criteria
- [WCAG 2.2 A - 2.3.1 Three Flashes or Below Threshold](https://www.w3.org/TR/WCAG22/#three-flashes-or-below-threshold)
- PDF-U/A - 7.1 General

---

### Captions for video (PDF-10-2)
All video (both live AND prerecorded) content MUST include accurate captions.

#### How to test
**Tool:** Adobe Acrobat Pro

1. Inspect the document for the presence of videos.
2. Verify that all video content provides accurate captions via an accessible mechanism.

#### Test outcomes
- **Pass**: All video content provides captions.

- **Fail**: Any video content does not provide captions.

- **NA**: No videos are present in the doc.

#### Related WCAG criteria
- [WCAG 2.2 A - 1.2.2 Captions (Prerecorded)](https://www.w3.org/TR/WCAG22/#captions-prerecorded)
- PDF-U/A - 7.18.6 Media

---

### Audio description for video (PDF-10-3)
If video content provides any information visually that is not described by an accompanying audio track, it MUST also include an Audio Description track that fully explains the visual information.

#### How to test
**Tool:** Adobe Acrobat Pro

1. Inspect the document for the presence of videos.
2. Verify that any video content that provides information visually that is not described by the default audio track provides that information via an Audio Description track, which fully explains the visual information.

#### Test outcomes
- **Pass**: All videos with visuals not fully explained by the default audio track have an Audio Description track that fully explains the visual information.

- **Fail**: Any video with visuals not fully explained by the default audio track does not have an Audio Description track to fully explains the visual information.

- **NA**: There are no videos in the document, or Audio Tracks, fully explain the visuals of the presented videos.

#### Related WCAG criteria
- [WCAG 2.2 AA - 1.2.5 Audio Description (Prerecorded)](https://www.w3.org/TR/WCAG22/#audio-description-prerecorded)
- PDF-U/A - 7.18.6 Media

---

### Transcripts for audio-only/video-only (PDF-10-4)
For audio-only and video-only media, a transcript MUST be provided which provides the same information as presented in the original media content.

#### How to test
**Tool:** Adobe Acrobat Pro

1. Inspect the document for the presence of audio-only AND/OR video-only content.
2. Verify that a transcript which provides the same information as presented in the original media content MUST be made available for all audio-only AND/OR video-only content.

#### Test outcomes
- **Pass**: All Audio-only AND/OR Video-only content has a transcript.

- **Fail**: Audio-only AND/OR Video-only content does not have a transcript.

- **NA**: There is no Audio-only/Video-only content is present in the document.

#### Related WCAG criteria
- [WCAG 2.2 A - 1.2.1 Audio-only & Video-only (Prerecorded)](https://www.w3.org/TR/WCAG22/#audio-only-and-video-only-prerecorded)
- PDF-U/A - 7.18.6 Media

</Breakless>

---

# index

---
title: Navigation
side_nav_title: Navigation
description: Find navigation requirements for testing PDFs.
side_nav_order: 5
---

<Breakless>

## Navigation (PDF-6)

### Page numbers (PDF-6-1)
Page numbering displayed in the PDF viewer page controls has the same page numbering as the document.

#### How to test
**Tool:** Adobe Acrobat Pro/PDF Accessibility Checker

1. Inspect the document for page numbers.
2. Use the keyboard shortcut CMD/CTRL+Shift+N to open a 'Go To Page' dialogue.
3. Enter a page number and click OK.
4. Verify that the entered page numbers match the actual page numbers of the document (from header/footer).

#### Test outcomes
- **Pass**:Page numbers in PDF reader accurately reflect the Document page number.

- **Fail**: Page numbers in PDF reader do not accurately reflect the document page number.

- **NA**: Page numbers are not available in the document.

#### Related WCAG criteria
- [WCAG 2.2 AA - 2.4.5 Multiple Ways](https://www.w3.org/TR/WCAG22/#multiple-ways)
- PDF-U/A - 7.17 Navigation

---

### Bookmarks (PDF-6-2)
Make it possible for users to locate content using bookmarks (outline entries in an Outline dictionary) in documents that are 21 pages or longer.

#### How to test
**Tool:** Adobe Acrobat Pro

1. Open the document in Adobe Acrobat Pro.
2. Open the bookmarks pane and verify that bookmarks are present.

#### Test outcomes
- **Pass**: Bookmarks are present.

- **Fail**: No bookmarks are present.

- **NA**: The document is less than 21 pages in length.

#### Related WCAG criteria
- [WCAG 2.2 AA - 2.4.5 Multiple Ways](https://www.w3.org/TR/WCAG22/#multiple-ways)
- PDF-U/A - 7.17 Navigation

</Breakless>

---

# index

---
title: Tables
side_nav_title: Tables
description: Find table requirements for testing PDFs.
side_nav_order: 6
---

<Breakless>

## Tables (PDF-7)

### Tables (PDF-7-1)
Tables should include headers. Tables can contain column headers, row headers or both. As much information as possible about the structure of tables needs to be available when assistive technology is relied upon. Headers play a key role in providing structural information. Structure elements of type TH should have a Scope attribute. If the table’s structure is not determinable via Headers and IDs, then structure elements of type TH shall have a Scope attribute.

Table tagging structures shall only be used to tag content presented within logical row and/or column relationships.

#### How to test
**Tool:** Adobe Acrobat Pro

1. Inspect the documents for tables.
2. Verify that all content that resembles a table is correctly tagged as a ``.
3. Verify that all table rows are appropriately tagged using the `<TR>` tag.
4. Verify that table headers are tagged with `<TH>` tags and have a defined scope and span (if applicable).
5. Verify that table data cells are properly tagged with `<TD>` tags.
6. Verify that table caption (if available) is tagged as `<Caption>` as its first or last child element of the `` tag.

#### Test outcomes
- **Pass**: All tabular data is correctly tagged with `` tags, row/column headers are marked with `<TH>` tags with an appropriate scope and Span attributes, Table rows are denoted with `<TR>` tags, table data cells are tagged with `<TD>` tags, and table captions(if available) are tagged with `<Caption>`.

- **Fail**: Any of the following conditions are not met: Tabular data is not tagged with Table tags, row/column headers are not tagged with `<TH>` tags or they lack a proper scope and Span attributes, Table rows are not tagged with `<TR>` tags, table data cells are not tagged with `<TD>` tags, or table captions(if available) are not tagged with `<Caption>`.

- **NA**: The content does not include any table elements.

#### Related WCAG criteria
- [WCAG 2.2 A - 1.3.1 Info and Relationships](https://www.w3.org/TR/WCAG22/#info-and-relationships)
- PDF-U/A - 7.5 Tables

---

### No layout tables (PDF-7-2)
Tables are only used for tabular data with a logical column/row relationship and not used for layout or positioning.

#### How to test
**Tool:** Adobe Acrobat Pro

1. Review the Tags panel in Acrobat for Table tags.
2. Confirm that no Table tags are used for layout purposes.

#### Test outcomes
- **Pass**: Tables are not used for layout purposes.

- **Fail**: Tables are used for layout purposes.

- **NA**: No Table tags are present.

#### Related WCAG criteria
- [WCAG 2.2 AA - 2.4.5 Multiple Ways](https://www.w3.org/TR/WCAG22/#multiple-ways)
- PDF-U/A - 7.17 Navigation

</Breakless>

---

# index

---
title: Tags
side_nav_title: Tags
description: Find tag requirements for testing PDFs.
side_nav_order: 2
---

<Breakless>

## Tags (PDF-3)

### Semantic tagging of text (PDF-3-1)
The most semantically appropriate tag shall be used for each logical element in the document content. Content shall be tagged in logical reading order.

#### How to test
**Tool:** Adobe Acrobat Pro

1. Open the tags panel and review the tags.
2. Verify that the tags selected are semantically appropriate for the content type in a logical reading order.
3. Verify that if non-standard (tag) structure types are used, they are mapped to the nearest functionally equivalent standard tags.
4. Verify that artifacts are not present in the tags tree.

#### Test outcomes
- **Pass**: The document is tagged and has semantically appropriate tags.

- **Fail**: The document is either untagged or has incorrect/non-semantic tags.

#### Related WCAG criteria
- [WCAG 2.2 - 4.1 Compatible](https://www.w3.org/TR/WCAG22/#compatible)
- PDF UA/1 - 7.1 General/7.2 Text

---

### Table of contents (PDF-3-2)
If a PDF contains a table of contents, it MUST contain bookmarks that link to the proper locations within the document.

#### How to test
**Tool:** Adobe Acrobat Pro

1. Inspect the document for the presence of a table of contents.
2. Verify that the Table of contents has links to the correct sections within the document.
3. Verify that all Table of Contents are correctly tagged as a `<TOC>`.
4. Verify that all Table of Contents Items are appropriately tagged using the `<TOCI>` tag and nested under `<TOC>`.
5. Verify that `<TOCI>` contains the related `<Reference>` tag with nested 'Link-OBJR' tag.
6. Verify that the caption (if available) is tagged as `<Caption>` and placed as a first child element of `<TOC>`.

#### Test outcomes
- **Pass**: The table of contents links to the correct section within the document and it is correctly tagged using `<TOC>`, `<TOCI>`, `<Reference>` tags and a `<caption>` tag if available.

- **Fail**: The table of contents either doesn't link to the correct sections within the document OR it is not correctly tagged using `<TOC>`, `<TOCI>`, `<Reference>` and `<caption>` tags.

- **NA**: A table of Contents is not present.

#### Related WCAG criteria
- [WCAG 2.2 AA - 2.4.5 Multiple Ways](https://www.w3.org/TR/WCAG22/#multiple-ways)
- PDF UA/1 - 7.18.1 General

---

### Headings (PDF-3-3)
Heading tags shall be used as follows:
- If any heading tags are used, H1 shall be the first.
- A document may use more than one instance of any specific tag level. For example, a tag level may be repeated if document content requires it.
- If document semantics require a descending sequence of headers, such a sequence shall proceed in strict numerical order and shall not skip an intervening heading level. H1, H2, H3, is permissible, while H1, H3, is not. Heading levels are said to descend if they use a sequence from H1 to H2, H2 to H3, H3 to H4, etc.
- A document may increment its heading sequence without restarting at H1 if document semantics require it. H1, H2, H3, H4, H3, is a permissible sequence.

**Note:** H1, H2, H3, H3, is a valid sequence if the content has one top-level heading, one second-level heading, and two consecutive third-level headings.

#### How to test
**Tool:** Adobe Acrobat Pro

1. Inspect the document for headings and corresponding tags.
2. Verify that all heading content is tagged as headings using only `<H1>` to `<H6>` tags.
3. Verify that headings follow a sequential order without any levels being skipped. For instance, the order should be Heading 1, followed by Heading 2, followed by Heading 3, and so on. There should be no omission of any numbers in the sequence.

#### Test outcomes
- **Pass**: Heading texts are tagged using only `<H1>` to `<H6>` tags and headings follow a sequential order, increasing and decreasing by one level without any skips.

- **Fail**: Heading texts are not tagged using `<H1>` to `<H6>` tags or Headings do not follow a sequential order and there are skips in the level increments.

#### Related WCAG criteria
- [WCAG 2.2 AA - 2.4.6 Headings and Labels](https://www.w3.org/TR/WCAG22/#headings-and-labels)
- [WCAG 2.2 A - 1.3.2 Meaningful Sequence](https://www.w3.org/TR/WCAG22/#meaningful-sequence)
- PDF UA/1 - 7.4.2 Numbered Headings

---

### Lists (PDF-3-4)
Lists shall be tagged with L tags with the following additional provisions:
- Individual list items shall be specified by LI tags. Lbl and LBody tags may be included.
- Lists shall only be used when required when the content is intended to be read as a list.

#### How to test
**Tool:** Adobe Acrobat Pro

1. Inspect the document for the text that looks like a list.
2. Verify that all Lists are correctly tagged as a `<L>`.
3. Verify that all List Items are appropriately tagged using the `<Li>` tag and nested under `<L>`.
4. Verify that all bullets or numbers tagged using `<Lbl>` and nested under `<Li>` as first child element.
5. Verify that List body content is tagged using `<LBody>` and nested under `<Li>` as a second child element.
6. Verify that caption(if available) is tagged as `<Caption>` and placed as a first child element of `<L>` before first `<Li>`.

#### Test outcomes
- **Pass**: All the lists are correctly tagged and properly nested using `<L>`, `<Li>`, `<Lbl>`, `<Lbody>` and `<Caption>` if available.

- **Fail**: Any list is not tagged using `<L>`, `<Li>`, `<Lbl>`, `<Lbody>` and `<Caption>` if available.

- **NA**: No lists are present.

#### Related WCAG criteria
- [WCAG 2.2 A - 1.3.1 Info and Relationships](https://www.w3.org/TR/WCAG22/#info-and-relationships)
- PDF UA/1 - 7.6 Lists

---

### Footnotes and endnotes (PDF-3-5)
Footnotes, endnotes, note labels and references (cross-references or citations to locations within the document) shall be tagged with a Note tag. Each note tag shall have a unique entry in the ID key

#### How to test
**Tool:** Adobe Acrobat Pro

1. Inspect the document for Footnotes and End notes.
2. Open the tags pane and review tags for all footnotes and endnotes. 
3. Verify that they are tagged rightly as `<Note>`.
4. Verify that each Note tag has unique entry in the ID key.
5. Verify that Note tag is always inside another block level tag.
6. Verify the footnotes are read immediately after the black level content where it was referenced (not end notes).

#### Test outcomes
- **Pass**: All footnotes and endnotes are correctly tagged as `<Note>`, each with unique IDs, and are in the correct reading order.

- **Fail**: One or more footnotes or endnotes are incorrectly tagged, lack unique IDs, or are not in the correct reading order.

- **NA**: The document has no footnotes or endnotes.

#### Related WCAG criteria
PDF UA/1 - 7.9 Notes and References

---

### Mathematical expressions (PDF-3-6)
All mathematical expressions shall be enclosed within a Formula tag and shall have an Alt attribute.

#### How to test
**Tool:** Adobe Acrobat Pro

1. Inspect the document for Math equations and formulas.
2. Access the tags panel and identify the tags related to the above content.
3. Verify that all math equations are rightly tagged as `<Formula>` and have an alt text explaining the equation in words.

#### Test outcomes
- **Pass**: All mathematical equations are tagged rightly as `<Formula>` and have right alt text.

- **Fail**: One or more mathematical equations are not tagged correctly.

- **NA**: No mathematical equations are present.

#### Related WCAG criteria
PDF UA/1 - 7. Mathematical Expressions

</Breakless>

---

# index

---
title: Text
side_nav_title: Text
description: Find text requirements for testing PDFs.
side_nav_order: 4
---

<Breakless>

## Text (PDF-5)

### Language of document (PDF-5-1)
Each document MUST have a language property that matches the language of the document.

#### How to test
**Tool:** Adobe Acrobat Pro

1. Open the document in Adobe Acrobat Pro and navigate to File > Properties > Advanced Tab.
2. Verify that the language used matches the content of the page.

#### Test outcomes
- **Pass**: A valid language is specified.

- **Fail**: A valid language is not specified.

#### Related WCAG criteria
- [WCAG 2.2 A - 3.1.1 Language of Page](https://www.w3.org/TR/WCAG22/#language-of-page)
- PDF UA/1 - 7.2 Text

---

### Tab and reading order (PDF-5-2)
Users shall be able to navigate through content in a logical order that is consistent with the meaning of the content.

#### How to test
**Tool:** Adobe Acrobat Pro

1. Use the Reading Order tool to verify the content is in the correct sequence.
2. Navigate through the page using a keyboard and verify that all interactive content appears in the right order when using the Tab key.

#### Test outcomes
- **Pass**: The sequence of the content and the order of tabbing through interactive elements is correct.

- **Fail**: Either the sequence of the content or the order of tabbing through interactive elements is incorrect.

#### Related WCAG criteria
- [WCAG 2.2 A - 1.3.2 Meaningful Sequence](https://www.w3.org/TR/WCAG22/#meaningful-sequence)
- PDF UA/1 - 7.2 Text

---

### Headings and footers (PDF-5-3)
Users shall be able to locate themselves in a document by providing running headers and footers in a consistent and predictable way via pagination artifacts.

#### How to test
**Tool:** Adobe Acrobat Pro

1. Inspect the document for running headers and footers.
2. Verify that they are consistent on all pages.
3. Verify that whether the content appears within the header or footer on multiple pages is redundant or not.
4. Verify that redundant content is marked as an artifact.

#### Test outcomes
- **Pass**: All headers and footers are consistent across the pages AND the redundant information is marked as an artifact.

- **Fail**: Any headers or footers are inconsistent across the pages OR the redundant information is not marked as an artifact.

- **NA**: No headers or footers are present in the document.

#### Related WCAG criteria
- [WCAG 2.2 AA - 3.2.3 Consistent Navigation](https://www.w3.org/TR/WCAG22/#consistent-navigation)
- PDF UA/1 - 7.8 Page Headers and Footers

---

### Language of parts (PDF-5-4)
A lang attribute MUST be set on every word or phrase that is in a different language than the document's main language.

#### How to test
**Tool:** Adobe Acrobat Pro

1. Find words or phrases in the document that are in a different language than the rest of the content.
2. Access the tags panel and identify the tags related to the content in the different language.
3. Verify the properties of these tags to ensure the correct language is selected for each word or phrase.

#### Test outcomes
- **Pass**: All words or phrases in a different language from the rest of the content have the correct language property set at the content level.

- **Fail**: Any words or phrases in a different language from the rest of the content do not have the correct language property set at the content level.

- **NA**: The document doesn't contain any words or phrases in a language different from the main document language.

#### Related WCAG criteria
- [WCAG 2.2 AA - 3.1.2 Language of Parts](https://www.w3.org/TR/WCAG22/#language-of-parts)
- PDF UA/1 - 7.2 Text

</Breakless>

---

# index

---
title: General
side_nav_title: General
description: Find general requirements for testing web experiences.
side_nav_aria_label: General requirements for web.
side_nav_order: 0

---

<Breakless>

## Page title (GEN-1)

### Accurate title (GEN-1-1)
An accurate and descriptive page `<title>` title must be included on every page or view.

#### How to test
**Tool:** ANDI

1. Inspect the HTML DOM and confirm that a `<title>` element is present.
2. Verify that the page title provided is accurate and descriptive of the purpose of the page and content.

#### Test outcomes
- **Pass**: Page title is accurate and descriptive of the page content.

- **Fail**: Page title is not included or page title is inaccurate and/or not descriptive of the page content.

#### Related WCAG criteria
[WCAG 2.2 A - 2.4.2 Page Titled](https://www.w3.org/TR/WCAG22/#page-titled)

---

### Unique title (GEN-1-2)
The page title must be unique and conform to a consistent structure among the other pages.

#### How to test
**Tool:** Browser Dev Tools (F12)

1. Inspect the target page.
2. Review the html `<title>` tag.
3. Verify that the page title is unique and conforms to a consistent structure among the other pages.

#### Test outcomes
- **Pass**: Page title is unique and conforms to a consistent structure among the other pages.

- **Fail**: Page title is not unique and/or it does not conform to a consistent structure among the other pages.

#### Related WCAG criteria
[WCAG 2.2 A - 2.4.2 Page Titled](https://www.w3.org/TR/WCAG22/#page-titled)

---

## Language (GEN-2)

### Lang attribute (GEN-2-1)
The applicable language must be defined on every page, inside the html tag.

#### How to test
**Tool:** Browser Dev Tools (F12)

1. Use the Inspect feature in the browser (for example: Chrome F12 dev tools) to open a view of the page HTML code.
2. Locate the `<html>` element at the beginning of the HTML DOM.
3. Confirm that the `lang=&quot;&quot;` attribute is correct for the language of the page content.

#### Test outcomes
- **Pass**: Correct page language is defined.

- **Fail**: Page language is not defined or the incorrect page language is defined.

#### Related WCAG criteria
[WCAG 2.2 A - 3.1.1 Language of Page](https://www.w3.org/TR/WCAG22/#language-of-page)

---

### Lang of parts of page (GEN-2-2)
A lang attribute must be set on every word or phrase that is in a different language than the page’s main language.

#### How to test
**Tool:** Browser Dev Tools (F12)

1. Locate any words or phrases in the page content that are in a language that is different from the language of the other content in the page. 
2. Use the Inspect feature in the browser (for example: Chrome F12 dev tools) to open a view of the page HTML code and inspect each of these words or phrases.
3. Confirm that each of these words or phrases is wrapped in a `<span>` element with a `lang=&quot;&quot;` attribute that is correct for the language of the word or phrase.

#### Test outcomes
- **Pass**: All words or pages which are in a different language than the global lang are marked up with the appropriate language.

- **Fail**: Words or pages which are in a different language than the global lang are not marked up with the appropriate language.

- **NA**: No words or phrases are in a different language from the global language.

#### Related WCAG criteria
[WCAG 2.2 AA - 3.1.2 Language of Parts](https://www.w3.org/TR/WCAG22/#language-of-parts)

---

## AT compatible (GEN-3)

### Support screen readers (GEN-3-1)
All features and functionality made available to users within the web application must be functionally supported with at least one screen reader per supported platform (for example: JAWS for Windows desktop, VoiceOver for MAC iOS, etc.).

#### How to test
**Tool:** Screen reader

Run through all use cases with each supported screen reader, confirming that all features and functionality are fully available to non-sighted users.

#### Test outcomes
- **Pass**: All features and functionality are fully available to non-sighted users.

- **Fail**: One or more features or functionality are not fully available to non-sighted users.

#### Related WCAG criteria
[WCAG 2.2 A - 4.1 Compatible](https://www.w3.org/TR/WCAG22/#compatible)

---

### Alerts read (GEN-3-2)
When alerts are shown on screen (for example: success, error, or status/informative) they must also be read aloud by each supported screen reader without receiving focus.

**Note:** Error messages that appear in-line upon leaving a form field are common examples.

#### How to test
**Tool:** Screen reader

Confirm that when alerts are shown on screen (for example: success, error, or status/informative) they are also read aloud by each supported screen reader. 

#### Test outcomes
- **Pass**: Alerts shown on screen are read aloud by each supported screen reader.

- **Fail**: Alerts shown on screen are not read aloud by each supported screen reader.

- **NA**: No alerts are shown on screen.

#### Related WCAG criteria
[WCAG 2.1 AA - 4.1.3 Status Messages](https://www.w3.org/TR/WCAG22/#status-messages)

---

## A11y validator (GEN-4)

### Use an Automated Testing Tool (GEN-4-1)
When run against the page, the automated validation tool must not report any errors.

#### How to test
**Tool:** Accessibility Insights

1. Run one automated validation tool of your choice against the page and confirm that it reports no errors. 
2. If errors are found, record a FAIL with a FAIL ID for each issue reported by the tool.

#### Test outcomes
- **Pass**: Automated tool returns zero errors.

- **Fail**: Automated tool returns one or more errors.

#### Related WCAG criteria
[WCAG 2.2 A & AA](https://www.w3.org/TR/WCAG22/)

</Breakless>

---

# index

---
title: Interactive
side_nav_title: Interactive
description: Find interactive requirements for testing web experiences.
side_nav_order: 2
---

<Breakless>

## Form elements (INT-1)

### Fully descriptive control labels (INT-1-1)
Controls and inputs must have one unique label attribute that fully describes the control’s purpose, including any supplementary information that the visual presentation may also provide (for example: related controls grouped together visually).

Some or all of a label MAY be hidden with CSS if the visual presentation provides the necessary context.

#### How to test
**Tool:** Accessibility Insights

1. In the target page, examine each control/input element.
2. Use Accessibility Insights > Adhoc Tools > Accessible Names.
3. Review the names and confirm they describe the elements.

#### Test outcomes
- **Pass**: All form controls have a unique label attribute that fully describes the control purpose and any supplementary information provided by the visual presentation.

- **Fail**: One or more form controls does not have a unique label fully describing the control purpose and any supplementary information provided by the visual presentation.

#### Related WCAG criteria
[WCAG 2.2 A - 3.3.2 Labels or Instructions](https://www.w3.org/TR/WCAG22/#labels-or-instructions)

---

### Info and relationships (INT-1-2)
Where visual presentation conveys information, structure, or relationships in content, the same information is available programmatically or in text.

#### How to test
**Tool:** Screen reader

1. Review the page and identify information, structure or relationships communicated visually (examples: large text conveys headings, bold or italic text conveys emphasis, spacing conveys paragraph structure, etc.).
2. Review any content identified in step 1 with a screen reader and confirm the same information, relationships, or structure is also conveyed programmatically.
3. If the information is not conveyed programmatically, confirm the information is conveyed in text.

#### Test outcomes
- **Pass**: All information, relationships, and structure conveyed through visual presentation is also conveyed programmatically or in text.

- **Fail**: There is information, relationships, or structure on the page that is conveyed visually but not programmatically or through text.

#### Related WCAG criteria
[WCAG 2.2 A - 1.3.1 Info and Relationships](https://www.w3.org/TR/WCAG22/#info-and-relationships)

---

### Group controls using fieldsets (INT-1-3)
If there is more than one distinct group of related form controls on a page, the related controls must be grouped programmatically. This may be done using either fieldset/legend or ARIA group role/text container. Text describing the logical grouping MAY be hidden off-screen if it isn't visually necessary.

#### How to test
**Tool:** Screen reader

If fieldsets or aria groups are used on the page to group more than one distinct group of related form controls, confirm that the legends/ARIA legends read properly, for example: before each label for the controls in the given group.

#### Test outcomes
- **Pass**: Related controls are grouped using Fieldset or ARIA group and the legend/ARIA legend is read correctly by screen reader.

- **Fail**: Related controls are not grouped using Fieldset or ARIA group or they are but the legend/ARIA legend is read incorrectly or not read by the screen reader.

- **NA**: No groups of related controls are present.

#### Related WCAG criteria
[WCAG 2.2 A - 1.3.1 Info and Relationships](https://www.w3.org/TR/WCAG22/#info-and-relationships)

---

### Required fields (INT-1-4)
Required fields/controls must use the `aria-required=&quot;true&quot;` attribute. They must also be communicated in text either at the beginning of the form or in-line.

Groups of checkboxes should not have the `aria-required` attribute and the required state should be indicated in text either at the beginning of the form, stating all fields are required, or in the group's fieldset legend instead.

#### How to test
**Tool:** Screen reader

1. Ensure that required fields are identified visually with text at the beginning of the form or in-line.
2. Tab through each control on the page and confirm that each required form control is announced as such by each supported screen reader.

#### Test outcomes
- **Pass**: All required fields are marked with `aria-required=&quot;true&quot;` and read correctly by a screen reader and text is available at the top of the form or in-line.

- **Fail**: One or more required field is not marked with `aria-required=&quot;true&quot;` and read correctly by a screen reader or text is not available at the top of the form or in-line.

#### Related WCAG criteria
[WCAG 2.2 A - 1.3.1 Info and Relationships](https://www.w3.org/TR/WCAG22/#info-and-relationships)

---

### Specify input purpose programmatically (INT-1-5)
If an input field is used to collect information about the user and the field supports autocomplete then the input field's purpose is identified programmatically.

#### How to test
**Tool:** Browser Dev Tools (F12)

1. Use the Browser inspection to inspect each input field on the page. to determine if the HTML atutocomplete or autofill attributes have been used.
2. If these attributes have been used, then they must match the type of information requested from the user.

#### Test outcomes
- **Pass**: There are no automated errors reported and all fields which have autocomplete or autofill defined have correct, valid values that match the requested information.

- **Fail**: One or more fields are detected which have incorrect or invalid values for autocomplete or autofill or the specified values do not match the information requested from the user.

- **NA**: No fields with autocomplete or autofill are present.

#### Related WCAG criteria
[WCAG 2.1 AA - 1.3.5 Identify Input Purpose](https://www.w3.org/TR/WCAG22/#identify-input-purpose)

---

### Visible and programmatic label consistency (INT-1-6)
If a control's visual label differs from the programmatic/accessible name value, then the programmatic/accessible name value includes the visual label.

#### How to test
**Tool:** ANDI

1. Use the ANDI tool and select Buttons/Links from the dropdown menu.
2. Use the ANDI Output section to determine whether or not any controls have a programmatic/accessible name value that is different from the visual label.
3. For any control that has a different visual label and ANDI output, confirm that the programmatic/accessible name value includes the visual label.
4. Repeat these steps using the ANDI Focusable Elements dropdown to review form fields.

#### Test outcomes
- **Pass**: All controls which have a different programmatic/accessible name value and visual label have the visual label text within the programmatic/accessible name value text string.

- **Fail**: One or more control which has a different programmatic/accessible name value and visual label does not have the visual label text within the programmatic/accessible name value text string.

- **NA**: No controls which have a different programmatic/accessible name value and visual label are present.

#### Related WCAG criteria
[WCAG 2.1 A - 2.5.3 Label in Name](https://www.w3.org/TR/WCAG22/#label-in-name)

---

### Multiple authentication methods (INT-1-7)
User authentication must avoid relying on a cognitive function test by providing multiple means of filling in authentication information.

#### How to test
**Tool:** Visual inspection

Ensure that authentication form fields allow any of the following:
- The fields allow autofill of information provided by the browser.
- Information may be pasted into the form fields.
- Biometrics can be used to sign into accounts.

#### Test outcomes
- **Pass**: The authentication fields allow autofill of stored information from the browser or information can be copied and pasted into the fields or biometrics (fingerprints, facial-scan, etc.) can be used to log in.

- **Fail**: The authentication fields do not allow autofill and information cannot be copied and pasted into the fields and biometrics cannot be used (for example: none of the pass criteria methods are used).

- **NA**: the page does not require interaction to authenticate.

#### Related WCAG criteria
[WCAG 2.2 AA - 3.3.8 Accessible Authentication Methods](https://www.w3.org/TR/WCAG22/#accessible-authentication-minimum)

---

## Form interactions (INT-2)

### On focus (INT-2-1)
Focusing or removing focus from an element does not cause a change of context.

#### How to test
**Tool:** Keyboard

1. Tab to each focusable element.
2. Tab away from each focusable element.
3. When focus lands on or leaves each element, confirm it does not cause a change of context.

#### Test outcomes
- **Pass**: Focusing or removing focus from an element does not cause a change of context.

- **Fail**: One or more elements cause a change of context when focused or focus is removed.

#### Related WCAG criteria
[WCAG 2.2 A - 3.2.1 On Focus](https://www.w3.org/TR/WCAG22/#on-focus)

---

### On input (INT-2-2)
Changing the value of any interactive element does not automatically cause a change of context unless the user has been advised beforehand.

#### How to test
**Tool:** Keyboard

1. Locate any elements on the page that has a value that can be updated (for example: checkboxes, radio buttons, selects, etc.).
2. Change the value for each element.
3. Confirm that unexpected changes do not occur.

#### Test outcomes
- **Pass**: No changes of context occur on value change or the user is advised beforehand.

- **Fail**: One or more changes of context occur on value change and the user is not advised beforehand.

- **NA**: No interactive elements can accept a value change.

#### Related WCAG criteria
[WCAG 2.2 A - 3.2.2 On Input](https://www.w3.org/TR/WCAG22/#on-input)

---

### Activate only on up event (INT-2-3)
Actions completed with mouse or touch input must not use the down-event to execute any part of the function.
-or-
Make sure there is a way for the user to abort or undo the action.
-or-
Allow the up-event to reverse any outcome of the preceding down-event

#### How to test
**Tool:** Mouse

Confirm that there are no actions which are completed using the down-event from mouse or touch input or that there is a way for the user to abort or undo the action or that the up-event allows the user to reverse any outcome of the preceding down-event.

#### Test outcomes
- **Pass**: No actions are completed using the down event or there is a way to abort or undo an action completed on the down-event or the up-event allows the reversal of the preceding down-event.

- **Fail**: Actions are completed using the down event and there is not a way to abort or undo the action and the up-event does not allow reversal of the preceding down-event.

#### Related WCAG criteria
[WCAG 2.1 A - 2.5.2 Pointer Cancellation](https://www.w3.org/TR/WCAG22/#pointer-cancellation)

---

### Redundant entry (INT-2-4)
If a page is contained within a process then information provided on the first step of the process is auto-filled in the next steps unless the information is required for security.

#### How to test
**Tool:** Visual inspection

Review the page to determine if it is a step in a process. Ensure that if information is provided in an earlier step in this process, that information is auto-filled in later steps.

#### Test outcomes
- **Pass**: Information provided during the process will autofill if later steps require the same information.

- **Fail**: Fields do not autofill when the same information has been provided on previous steps.

- **NA**: The page does not contain any process-based functionality or information reentry is essential or required for security.

#### Related WCAG criteria
[WCAG 2.2 A - 3.3.7 Redundant Entry](https://www.w3.org/TR/WCAG22/#redundant-entry)

---

## Errors & messaging (INT-3)

### Check for errors (INT-3-1)
If an input error is automatically detected, the item that is in error is identified and the error is described to the user in text.

#### How to test
**Tool:** Visual inspection

1. Identify any inputs that have automatic validation.
2. For each input, verify that errors are described in text.

#### Test outcomes
- **Pass**: Errors are identified and the errors are described to the user in text.

- **Fail**: Errors are identified but the errors are not described to the user in text.

- **NA**: There are no inputs with automatic validation.

#### Related WCAG criteria
- [WCAG 2.2 A - 3.3.1 Error Identification](https://www.w3.org/TR/WCAG22/#error-identification)
- [WCAG 2.2 AA - 3.3.3 Error Suggestion](https://www.w3.org/TR/WCAG22/#error-suggestion)

---

### Summary before submit (INT-3-2)
If user input is collected across multiple pages in order to execute a transaction of some kind the user must be presented with a summary of the input before submitting. The user must be able to change input prior to final submission after reviewing.

#### How to test
**Tool:** Visual inspection

Examine the target page to determine whether it allows users to:
- make any legal commitments or financial transactions, or
- modify or delete data in a data storage system, or
- Submit test responses.
- If the page does allow such actions, verify that the following are true:
     - the user is presented with a summary of the input before submitting.
     - user can review, confirm, and correct information before finalizing the submission.

#### Test outcomes
- **Pass**: A summary of user input is provided prior to final submit and the user can edit or make corrections as needed.

- **Fail**: A summary of user input is not provided prior to final submit or the user cannot edit or make corrections as needed.

- **NA**: User input is not collected across pages to execute a transaction.

#### Related WCAG criteria
[WCAG 2.2 AA - 3.3.4 Error Prevention](https://www.w3.org/TR/WCAG22/#error-prevention-legal-financial-data)

---

### Error suggestion (INT-3-3)
When errors are detected, suggestions are provided to correct them, unless it would jeopardize the security or purpose of the content.

#### How to test
**Tool:** Visual inspection

1. Locate any errors that can appear on the page.
2. Trigger each error.
3. Confirm that when possible, an error message describes how to correct the error (eg "username field is required" or "phone number must contain 10 digits").

#### Test outcomes
- **Pass**: Suggestions to fix errors are present.

- **Fail**: One or more errors exist but users are not informed how to fix the errors.

- **NA**: No errors exist on the page.

#### Related WCAG criteria
[WCAG 2.2 A - 3.3.3 Error Suggestion](https://www.w3.org/TR/WCAG22/#error-suggestion)

---

### Highlight in-line errors visually (INT-3-4)
When an error is detected using in-line validation, highlight the field (for example: with a bold red border, error icon with proper alternative text) and place error helper text near it.

#### How to test
**Tool:** Visual inspection

Confirm that when an error is detected using in-line validation, the visual UI highlights the fields with errors (for example: with a red border) and places error helper text above or below each one.

#### Test outcomes
- **Pass**: When an error is detected using in-line validation, the visual UI highlights the field and places error helper text near it.

- **Fail**: For one or more client-side validated forms when an error is detected using client side validation, the visual UI does not highlight the field or place error helper text near it.

- **NA**: No forms are present.

#### Related WCAG criteria
- [WCAG 2.2 A - 3.3.1 Error Identification](https://www.w3.org/TR/WCAG22/#error-identification)
- [WCAG 2.2 AA - 3.3.3 Error Suggestion](https://www.w3.org/TR/WCAG22/#error-suggestion)

---

## Interactive controls (INT-4)

### Link text in context (INT-4-1)
The destination of a link is clear from either the link text alone or the link text combined with surrounding programmatically associated text.

#### How to test
**Tool:** Screen reader

1. Use a screen reader to navigate to each link on the page.
2. Confirm that one of the following is true:
- The name of the link provides sufficient information to understand its destination.
or
- The link destination is clear based on its name and surrounding programmatically associated content (for example: text in the same paragraph, list item, or table cell; content in a table header associated with a table cell containing the link; etc.).

#### Test outcomes
- **Pass**: The destination of all links is clear based on the link text alone or the link text and surrounding programmatically associated text.

- **Fail**: The destination of one or more links on the page is unclear and the surrounding programmatically associated context also does not provide information about the link's purpose.

- **NA**: No links are present.

#### Related WCAG criteria
[WCAG 2.2 A - 2.4.4 Link Purpose](https://www.w3.org/TR/WCAG22/#link-purpose-in-context)

---

### Valid link href attribute (INT-4-2)
Links must contain a valid href attribute value and must not point to `&quot;javascript:void(0);&quot;` nor `&quot;#&quot;`.

#### How to test
**Tool:** ANDI

Bring up the list of links with ANDI if available and confirm no links HREF points to `&quot;javascript:void(0);&quot;` nor `&quot;#&quot;`.

#### Test outcomes
- **Pass**: All links contain valid href attribute values.

- **Fail**: One or more links do not contain valid href values.

- **NA**: No links are present.

#### Related WCAG criteria
[WCAG 2.2 A - 4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value)

---

### Click and drag movements (INT-4-3)
An action that relies on clicking and dragging of content can also be achieved by a single pointer without dragging unless dragging is essential to the activity.
- Example of single pointer Pass: A quiz relies on users clicking and dragging information into the correct bucket. Users are also able to click once to select an option, then click on the correct bucket.
- Example of essential activity: A medical app requires clicking and dragging an object to a target to accurately measure the user’s precision.

#### How to test
**Tool:** Visual inspection

1. Visually inspect the page to determine whether any functionality requires a user to click and move their mouse to access content.
2. For any dragging content, confirm that it can be used with a single pointer without dragging.

#### Test outcomes
- **Pass**: All click and drag functionality can also be performed with a single pointer or the dragging movement is essential.

- **Fail**: Click and drag functionality cannot be completed with a single pointer.

- **NA**: The page does not contain click and drag functionality.

#### Related WCAG criteria
[WCAG 2.2 AA - 2.5.7 Dragging Movements](https://www.w3.org/TR/WCAG22/#dragging-movements)

---

### Target size (INT-4-4)
Actionable components have a minimum target size of 24x24 CSS pixels except for:

Objects with a target offset of at least 24px.
- For example, a 20px width “Cancel” button has its right most edge at least 4px away from a “Submit” button placed on the right.
Inline content within a sentence or block of text.
- For example, a wiki paragraph has multiple instances of hyperlinked text. Increasing the height and width of these links would impact the presentation of text and make it more difficult to read.

#### How to test
**Tool:** Browser Dev Tools (F12)

Use browser inspect tool to view the CSS values under the “Computed” tab. Find the height and width properties for the component. 
Ensure that each control has a width and height greater than or equal to 24px or 
- For example, a 20px width “Cancel” button has its right most edge at least 4px away from a “Submit” button placed on the right.

#### Test outcomes
- **Pass**: Both height and width are greater than or equal to 24px or less than 24px with sufficient spacing between controls.

- **Fail**: Either the height or width is less than 24px and the center of the control is less than 24px from another control.

- **NA**: Target is a link or button in a block of text that requires a specific presentation.

#### Related WCAG criteria
[WCAG 2.2 AA - 2.5.8 Target Size (Minimum)](https://www.w3.org/TR/WCAG22/#target-size-minimum)

---

### Name (INT-4-5)
All interactive elements must have a programmatic name accessible to assistive technology

#### How to test
**Tool:** Screen reader

1. Review each interactive element with a screen reader.
2. For each interactive element, verify the screen reader announces the name of the element.

#### Test outcomes
- **Pass**: All interactive elements have a name announced by the screen reader.

- **Fail**: One or more interactive elements do not have a name announced by the screen reader.

#### Related WCAG criteria
[WCAG 2.2 A - 4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value)

---

### Role (INT-4-6)
All elements with semantic meaning have a valid, accurate programmatic role accessible to assistive technology

#### How to test
**Tool:** Screen reader

1. Locate all elements on the page with semantic meaning. (for example: headings, buttons and links, dialogs, etc…).
2. For each element with semantic meaning, verify the screen reader announces the role of the element. 
3. Verify that the role announced for the element is valid and matches the semantic meaning of the element (for example: a link announces a link role, a button announces a button role, etc.).

#### Test outcomes
- **Pass**: All elements with semantic meaning have a role announced by the screen reader that matches the semantic meaning of the element.

- **Fail**: One or more semantic elements do not have a role announced by the screen reader or the role announced does not match the semantic meaning of the element.

#### Related WCAG criteria
[WCAG 2.2 A - 4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value)

---

### Value, states, properties (INT-4-7)
States, properties, and values of elements are programmatically available to assistive technology, Any changes to these items are also communicated to assistive technology.

#### How to test
**Tool:** Screen reader

1. Locate all elements on the page which have states, properties, and/or values associated (for example: pressed/invalid state, an error message property on an invalid input, a user-input text string value in a "name" text field, etc.).
2. For each identified state, property, or value, confirm that the screen reader announces it when interacting with the associated element.

**Note:** If a state, property, or value has changed, the screen reader can determine the change.

#### Test outcomes
- **Pass**: All states, properties, and values are announced by the screen reader when interacting with the associated element.

- **Fail**: One or more states, properties, or values are not announced to the screen reader when interacting with the associated element.

- **NA**: No elements with states, properties, or values are present.

#### Related WCAG criteria
[WCAG 2.2 A - 4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value)

---

## Diverse user needs (INT-5)

### Pause, stop, hide moving content (INT-5-1)
A mechanism must be provided to pause, stop, or hide any content that meets the following criteria:
- Starts automatically
- Is presented in parallel with other content
and
- moves, blinks or scrolls for >5 seconds
or 
- All auto-updating content regardless of duration

#### How to test
**Tool:** Visual inspection

1. Perform a visual inspection of the page.
2. Confirm that for any content that meets the following criteria, a mechanism is provided to pause, play, or hide the applicable content:
- Starts automatically.
- Is presented in parallel with other content.
and
- moves, blinks or scrolls for >5 seconds.
or 
- All auto-updating content regardless of duration.

#### Test outcomes
- **Pass**: A mechanism is provided to pause, stop, or hide auto-playing; moving or blinking; auto-updating content.

- **Fail**: A mechanism is not provided to pause, stop, or hide auto-playing; moving or blinking; auto-updating content.

- **NA**: No auto-playing; moving or blinking; auto-updating content is present.

#### Related WCAG criteria
[WCAG 2.2 A - 2.2.2 Pause, Stop, Hide](https://www.w3.org/TR/WCAG22/#pause-stop-hide)

---

### Pause or adjust volume for auto playing audio (INT-5-2)
For any audio which 1) plays automatically and 2) lasts for >3 seconds, one of the following must be true:
- A mechanism to pause the content is presented to the user
or
- A mechanism for adjusting the volume of the content is presented to the user and it does not rely on the system audio levels to adjust the volume.

#### How to test
**Tool:** Visual inspection

Confirm that for any audio which 1) plays automatically and 2) lasts for >3 seconds, one of the following is true:
- A mechanism to pause the content is presented to the user.
or
- A mechanism for adjusting the volume of the content is presented to the user and it does not rely on the system audio levels to adjust the volume.

#### Test outcomes
- **Pass**: For all content which plays automatically and lasts for more than 3 seconds a mechanism is provided to pause or adjust volume.

- **Fail**: A mechanism is not provided to pause or adjust volume for all content which plays automatically and lasts for more than 3 seconds.

- **NA**: No content which plays automatically and lasts for more than 3 seconds is present.

#### Related WCAG criteria
[WCAG 2.2 A - 1.4.2 Audio Control](https://www.w3.org/TR/WCAG22/#audio-control)

---

### No blinking or flashing (INT-5-3)
Content that blinks or flashes rapidly must never be used.

**Note:** "Rapidly" is blinking/flashing more than 3 times in 1 second. If there is any doubt about the frequency of flashing then this would fail.

#### How to test
**Tool:** Visual inspection

1. Perform a visual inspection of the page.
2. Confirm that each page contains no content that blinks or flashes.

#### Test outcomes
- **Pass**: Content that blinks or flashes is not used.

- **Fail**: Content that blinks or flashes is used.

#### Related WCAG criteria
[WCAG 2.2 A - 2.3.1 Three Flashes or Below Threshold](https://www.w3.org/TR/WCAG22/#three-flashes-or-below-threshold)

---

### Warn about timeout (INT-5-4)
Users must be warned prior to when a session times out and expires.

#### How to test
**Tool:** Visual inspection

Confirm that users are warned prior to when a session times out and expires.

#### Test outcomes
- **Pass**: Session timeout warning occurs prior to session time out and expiration.

- **Fail**: Session timeout occurs without warning.

- **NA**: No session timeout is present.

#### Related WCAG criteria
[WCAG 2.2 A - 2.2.1 Timing Adjustable](https://www.w3.org/TR/WCAG22/#timing-adjustable)

---

### Extend timeout (INT-5-5)
When a session timeout warning occurs, users must be given at least 30 seconds to take action in order to avoid a session time out by extending the time limit (of a session) via a "simple" user action (for example: "press the space bar").

#### How to test
**Tool:** Visual inspection

Confirm that users are given at least 30 seconds to take action in order to avoid a session time out by extending the time limit (of a session) via a "simple" user action (for example: "press the space bar").

#### Test outcomes
- **Pass**: Users are given at least 30 seconds to extend the session via a simple user action.

- **Fail**: Users are given less than 30 seconds to extend the session via a simple user action.

- **NA**: No session timeout is present.

#### Related WCAG criteria
[WCAG 2.2 A - 2.2.1 Timing Adjustable](https://www.w3.org/TR/WCAG22/#timing-adjustable)

---

### Flexible orientation (INT-5-6)
Content must adapt to the device orientation when orientation is changed from portrait to landscape mode unless a specific orientation is required.

#### How to test
**Tool:** System Settings

Set display orientation to each orientation mode (portrait and landscape) and review how the content responds. 

This can be done using OS settings (Start > Settings > System > Display) or inspecting the page in your browser and using the device list to change orientations.
https://developer.chrome.com/docs/devtools/device-mode/orientation/

#### Test outcomes
- **Pass**: Content adapts to all display orientations.

- **Fail**: Content does not adapt to all display orientations.

- **NA**: A specific display orientation is essential (for example: bank check).

#### Related WCAG criteria
[WCAG 2.1 AA- 1.3.4 Orientation](https://www.w3.org/TR/WCAG22/#orientation)

---

### Motion control (INT-5-7)
If functionality can be operated or activated by device or user motion then it can also be operated or activated through UI components and motion actuation can be turned off to avoid unintentional activation by the user.

#### How to test
For all functionality that can be operated or activated by moving the device or user motion input confirm that the same functionality can be operated or activated through UI components and confirm that the motion actuation can be turned off by the user

#### Test outcomes
- **Pass**: All functionality that can be operated or activated by device or user motion has a UI control alternative and motion actuation can be turned off by the user.

- **Fail**: Any aspect of functionality that can be operated or activated by device or user motion does not have a UI control alternative or motion actuation cannot be turned off by the user.

- **NA**: No functionality that can be operated or activated by device or user motion is present.

#### Related WCAG criteria
[WCAG 2.1 A - 2.5.4 Motion Actuation](https://www.w3.org/TR/WCAG22/#motion-actuation)

</Breakless>

---

# index

---
title: Navigation and wayfinding
side_nav_title: Navigation and wayfinding
description: Find navigation and wayfinding requirements for testing web experiences.
side_nav_order: 3
---

<Breakless>

## Keyboard support (NAV-1)

### Keyboard support (NAV-1-1)
All functionality and content must be available to users via keyboard only, without requiring specific timing of keystrokes.

#### How to test
**Tool:** Keyboard

Run through all use cases using keyboard only (for example: without a mouse), confirming that all features and functionality are fully available to users.

#### Test outcomes
- **Pass**: All features and functionality are fully available to keyboard users.

- **Fail**: One or more features or functionality are not fully available to keyboard users.

#### Related WCAG criteria
[WCAG 2.2 A - 2.1.1 Keyboard](https://www.w3.org/TR/WCAG22/#keyboard)

---

### No keyboard trap (NAV-1-2)
If any part of the UI takes control of keyboard focus (for example: PDF viewer or modal window) it must, through keyboard commands only, allow focus to return to the launching element and browser. 

#### How to test
**Tool:** Keyboard

Run through all use cases using keyboard only (for example: without a mouse), confirm that no UI elements take control of keyboard focus unless they also return focus.

#### Test outcomes
- **Pass**: No UI elements take control of keyboard focus without returning it.

- **Fail**: One or more UI elements takes control of keyboard focus and does not return it.

#### Related WCAG criteria
[WCAG 2.2 A - 2.1.2 No Keyboard Trap](https://www.w3.org/TR/WCAG22/#no-keyboard-trap)

---

### Mouse hover and keyboard focus are equivalent (NAV-1-3)
Content which is hidden until it receives mouse hover and then becomes visible must also be shown when it receives keyboard focus and hidden again when focus is removed.

#### How to test
**Tool:** Keyboard

1. Run through all use cases using the keyboard only (for example: without a mouse).
2. Confirm that any mouse hover events are also available to the keyboard when the keyboard focus is placed on the element.

#### Test outcomes
- **Pass**: All mouse hover events are also available to the keyboard when the keyboard focus is placed on the element.

- **Fail**: One or more mouse hover events are not available to the keyboard when the keyboard focus is placed on the element.

- **NA**: Mouse hover events are not present.

#### Related WCAG criteria
- [WCAG 2.1 AA - 1.4.13 Content on Hover or Focus](https://www.w3.org/TR/WCAG22/#content-on-hover-or-focus)
- [WCAG 2.2 A - 2.1.1 Keyboard](https://www.w3.org/TR/WCAG22/#keyboard)

---

### Content on hover or focus (NAV-1-4)
For tooltips and components that show hidden content when they receive keyboard or pointer focus and hidden after removal of focus ensure they are dismissible, hoverable, and persistent.

#### How to test
**Tool:** Keyboard/Mouse

1. For tooltips and components that show hidden content when they receive keyboard or pointer focus and hidden after removal of focus.
2. ensure they are dismissible, hoverable, and persistent.

#### Test outcomes
- **Pass**: All of the hover show/hide content is dismissible, hoverable, and persistent.

- **Fail**: Hover show/hide content is not all dismissible, hoverable, and persistent.

- **NA**: No hover show/hide content is present.

#### Related WCAG criteria
[WCAG 2.1 AA - 1.4.13 Content on Hover or Focus](https://www.w3.org/TR/WCAG22/#content-on-hover-or-focus)

---

### Pointer and multipoint gestures (NAV-1-5)
An action that is performed by a 'path-based gesture' or multipoint gesture must also be completable using a single pointer gesture and a keyboard or alternative input device.

#### How to test
**Tool:** Mouse

1. Use the keyboard to navigate to all path-based or multipoint gesture operable controls and confirm that they can all be operated with keyboard control.
2. Use the mouse to interact with all path-based or multipoint gesture operable controls and confirm that they can all be operated with a single pointer gesture control as well.

#### Test outcomes
- **Pass**: All actions that can be performed by a path-based or multipoint gesture can also be completed with a keyboard and a single pointer gesture (individual mouse clicks).

- **Fail**: One or more actions that can be performed by a path-based or multipoint gesture cannot be completed with a keyboard or a single pointer gesture (individual mouse clicks).

- **NA**: no actions that can be performed by a path-based or multipoint gesture are present.

#### Related WCAG criteria
[WCAG 2.1 A - 2.5.1 Pointer Gestures](https://www.w3.org/TR/WCAG22/#pointer-gestures)

---

### Single character keyboard shortcuts (NAV-1-6)
If a single character shortcut is used then users must have the option to either turn it off or remap it to one or more non-printable keyboard characters.
-or-
Make sure the single character shortcut is only active when the component it affects has focus.

#### How to test
**Tool:** Keyboard

Confirm that where a single character shortcut is used that users have the option to either turn it off or remap it to one or more non-printable keyboard characters.
-or-
Make sure the single character shortcut is only active when the component it affects has focus.

#### Test outcomes
- **Pass**: For all single character shortcuts, users have the option to either turn off or remap it to one or more non-printable keyboard characters or the single character shortcut is only active when the component it affects has focus.

- **Fail**: For all single character shortcuts, users do not have the option to either turn off or remap it to one or more non-printable keyboard characters and the single character shortcut is active at all times.

- **NA**: No single character shortcuts are present.

#### Related WCAG criteria
[WCAG 2.1 A - 2.1.4 Character Key Shortcuts](https://www.w3.org/TR/WCAG22/#character-key-shortcuts)

---

### Skip to main content link (NAV-1-7)
A "skip to main content" link must be included on every page as the first link (or second if "skip to login" link is present) on the page. The link must skip to the main content of the page or the errors summary if present and may be visually hidden until it has focus.

#### How to test
**Tool:** Keyboard

Hit Tab after the page loads. Confirm that the first or second link on the page is "skip to main content" - it may be visibly hidden until it receives focus. If running the test on a Single Page Application (SPA) refresh the page and confirm that the first or second link is “Skip to main content”.

#### Test outcomes
- **Pass**: A skip to main content link is provided and it is fully operational.

- **Fail**: A skip to main content link is not provided or the skip to content link is not fully operational.

#### Related WCAG criteria
[WCAG 2.2 A - 2.4.1 Bypass Blocks](https://www.w3.org/TR/WCAG22/#bypass-blocks)

---

## Focus & tab order (NAV-2)

### Visible keyboard focus (NAV-2-1)
During keyboard navigation, the keyboard focus indicator is visible.

#### How to test
**Tool:** Keyboard

1. Tab through the entire page.
2. Confirm each focusable element has a visible focus indicator.

#### Test outcomes
- **Pass**: Each focusable element has a visible focus indicator.

- **Fail**: One or more focusable elements do not have a visible focus indicator.

#### Related WCAG criteria
- [WCAG 2.2 AA - 2.4.7 Focus Visible](https://www.w3.org/TR/WCAG22/#focus-visible)
- [WCAG 2.2 AAA - 2.4.13 Focus Appearance](https://www.w3.org/TR/WCAG22/#focus-appearance)

---

### Focus not obscured (NAV-2-2)
When a focusable element has keyboard focus, the element is at least partially visible.

#### How to test
**Tool:** Keyboard

1. Tab through the entire page.
2. For each focusable element, when it has focus, confirm at least part of the element is visible (not fully obscured by other content or off the viewport).

**Note:** If content can be repositioned by the user, only test the initial position.

#### Test outcomes
- **Pass**: Focusable elements are at least partially visible when focused.

- **Fail**: One or more focusable elements are fully obscured when focused.

#### Related WCAG criteria
[WCAG 2.2 AA - 2.4.11 Focus Not Obscured (Minimum)](https://www.w3.org/TR/WCAG22/#focus-not-obscured-minimum)

---

### Focus order (NAV-2-3)
Tab focus must follow a logical and meaningful order that preserves relationships and matches how the page is naturally read.

#### How to test
**Tool:** Keyboard

1. Navigate through all interactive elements on the page using the tab key.
2. Confirm that focus moves to each element in a logical order (generally top to bottom, left to right).

#### Test outcomes
- **Pass**: The focus order is logical and meaningful, preserving relationships and matching how the page is naturally read.

- **Fail**: The focus order is not logical. The meaning or relationships in the content are affected.

#### Related WCAG criteria
[WCAG 2.2 A - 2.4.3 Focus Order](https://www.w3.org/TR/WCAG22/#focus-order)

---

## Landmarks (NAV-3)

### Appropriate use of landmark regions (NAV-3-1)
The page must have a 'Main' landmark region defined at a minimum and Banner, Navigation, Search, Complementary, and ContentInfo roles are present if these content types are present in the page.

#### How to test
**Tool:** Accessibility Insights

1. Open the page in the Chrome browser and use Accessibility Insights > Adhoc Tools >Landmarks to visualize the landmark regions that are present in the page. 
2. Confirm that the page has a 'Main' landmark region defined at a minimum. 
3. Confirm that the Banner, Navigation, and ContentInfo roles are present if these content types are present in the page.

#### Test outcomes
- **Pass**: The page contains a main landmark region and if content suited for a navigation, banner, or contentinfo region is present then the appropriate roles are applied to each content area respectively.

- **Fail**: The page does not contain a main landmark region or content suited for a navigation, banner, or contentinfo region is present and the appropriate roles are not
applied to each content area respectively.

- **NA**: The page content is not substantial enough to be grouped in one or more landmark regions.

#### Related WCAG criteria
[WCAG 2.2 A - 2.4.1 Bypass Blocks](https://www.w3.org/TR/WCAG22/#bypass-blocks)

---

### Keep all content in appropriate regions (NAV-3-2)
All rendered content must be within the appropriate landmark region and the Main landmark must contain all of the primary page content and no blocks of content that repeat on multiple pages are within the Main landmark.

#### How to test
**Tool:** Accessibility Insights

Using the Accessibility Insights Landmarks tool, examine the landmark regions in the page and confirm that: 
1. All page content is within a landmark region.
2. All primary page content is within the Main landmark region.
3. No content that repeats on multiple pages is within the Main landmark region.

#### Test outcomes
- **Pass**: All page content is within the appropriate landmark region.

- **Fail**: One or more blocks of page content are not within a landmark region or the Main landmark region does not include all primary page content or content that repeats on multiple pages is within the Main landmark region.

#### Related WCAG criteria
[WCAG 2.2 A - 2.4.1 Bypass Blocks](https://www.w3.org/TR/WCAG22/#bypass-blocks)

---

### Redundant landmarks have unique names (NAV-3-3)
If a page has multiple landmarks of the same type (for example: Main Nav and Sub Nav), those regions must have unique names applied using an appropriate naming technique and the landmark role type must not be included in the name. 

#### How to test
**Tool:** Accessibility Insights

1. Use Accessibility Insights > Adhoc Tools > Landmarks to review all of the landmarkroles in the page.
2. Locate any instance of two or more landmarks of the same type (for example: Main Nav and Sub Nav).
3. Confirm that each duplicate landmark has a unique name that does not include the landmark role type in the name to help screen reader users distinguish between the two.

#### Test outcomes
- **Pass**: All landmark regions of the same role type have unique names applied and the name for each does not include the role type.

- **Fail**: Two or more landmark roles of the same type are present and they do not have unique names applied or the name of one or more region includes the role type in the name value.

- **NA**: No landmark regions of the same role type are present.

#### Related WCAG criteria
[WCAG 2.2 AA - 2.4.6 Headings and Labels](https://www.w3.org/TR/WCAG22/#headings-and-labels)

---

## Consistent experience (NAV-4)

### Same relative order (NAV-4-1)
Components, like links, buttons, or contact forms, that appear on multiple pages must appear in the same relative order on every page.

#### How to test
**Tool:** Visual inspection

1. Perform a visual inspection of the page looking for navigation components.
2. Confirm that components (links, buttons, contact forms, etc.) that appear on multiple pages appear in the same relative order on every page.

#### Test outcomes
- **Pass**: Components that appear on multiple pages appear in the same relative order on every page.

- **Fail**: One or more component that appears on multiple pages does not appear in the same relative order on every page.

- **NA**: No component appears on multiple pages.

#### Related WCAG criteria
[WCAG 2.2 AA - 3.2.3 Consistent Navigation](https://www.w3.org/TR/WCAG22/#consistent-navigation)

---

### Name consistently (NAV-4-2)
Consistent labels, names, and text alternatives must be used for content that has the same functionality.

#### How to test
**Tool:** Visual inspection

Confirm that content with the same functionality has consistent labels, names, and text alternatives.

#### Test outcomes
- **Pass**: Content with the same functionality has consistent labels, names, and text alternatives.

- **Fail**: Content with the same functionality does not have consistent labels, names, or text alternatives.

- **NA**: No content with the same functionality is present.

#### Related WCAG criteria
[WCAG 2.2 AA - 3.2.4 Consistent Identification](https://www.w3.org/TR/WCAG22/#consistent-identification)

---

### Consistent help (NAV-4-3)
If a page includes the help options listed below, they are in the same location on similar pages:
- Human contact details;
- Human contact mechanism;
- Self-help option;
- A fully automated contact mechanism.

#### How to test
**Tool:** Visual inspection

1. Locate if any of the listed help options in exist on the page:
    - Human contact details;
    - Human contact mechanism;
    - Self-help option;
    - A fully automated contact mechanism.
2. Determine if the help is in the same location across similar pages.

#### Test outcomes
- **Pass**: Help across similar pages is in the same location.

- **Fail**: Help across similar pages is not in the same location.

- **NA**: No help options exist on the page.

#### Related WCAG criteria
[WCAG 2.2 A - 3.2.6 Consistent Help](https://www.w3.org/TR/WCAG22/#consistent-help)

---

### More than one way to find content (NAV-4-4)
Users must be provided more than one way to find content within a website except when the web page is the result of a step or process. This provision must include two or more of the following navigational methods:
- Links to navigate to related Web pages
- a Table of Contents
- a Site Map
- a search function 
- a list of links to all other Web pages
- Linking to all of the pages on the site from the home page

#### How to test
**Tool:** Visual inspection

1. Review the page and site navigation structure.
2. Confirm that the site provides at least 2 of the following ways to find content:
- Links to navigate to related Web pages
- Table of Contents
- Site Map
- Search function
- List of links to all other Web pages
- Linking to all of the pages on the site from the home page

 Exception: Small sites (4 pages or fewer) can meet this requirement if the main navigation menu links to all other pages.

#### Test outcomes
- **Pass**: The site provides 2 or more ways to find content.

- **Fail**: The site provides fewer than 2 ways to find content.

#### Related WCAG criteria
[WCAG 2.2 AA - 2.4.5 Multiple Ways](https://www.w3.org/TR/WCAG22/#multiple-ways)

</Breakless>

---

# index

---
title: Text requirements for web
side_nav_title: Text
description: Find text requirements for testing web experiences.
side_nav_aria_label: Text requirements for web.
side_nav_order: 1

---

<Breakless>

## Heading structure (TXT-1)

### Headings and labels (TXT-1-1)
Headings and labels must accurately describe their content.

#### How to test
**Tool:** Accessibility Insights

1. Reveal headings via Accessibility Insights > Ad hoc tools>Accessible Names.
2. View all headings and labels on the page.
3. Confirm that the page headings and labels accurately describe their content.

#### Test outcomes
- **Pass**: Headings and labels are used and they accurately describe their content.

- **Fail**: Headings and labels are not used or they do not accurately describe their content.

- **NA**: There is not sufficient content to warrant the use of headings or labels.

#### Related WCAG criteria
[WCAG 2.2 AA - 2.4.6 Headings and Labels](https://www.w3.org/TR/WCAG22/#headings-and-labels)

---

### Use a single descriptive H1 (TXT-1-2)
Each page must have only one H1 which is descriptive of the overall page topic/purpose. The H1 and the page title should be similar and consistent. 

#### How to test
**Tool:** Accessibility Insights

1. Reveal headings via Accessibility Insights > Ad hoc tools > Headings.
2. View all headings and confirm there is a single H1 on the page.
3. Confirm that the H1 is descriptive of the overall page topic/purpose.
4. Confirm that the H1 and page title are similar and consistent.

#### Test outcomes
- **Pass**: There is only one H1 level heading present and it is descriptive of the page topic/purpose and similar to the page title.

- **Fail**: There are two or more H1 level headings present or the H1 is not descriptive of the page topic/purpose or not similar to the page title.

#### Related WCAG criteria
[WCAG 2.2 A - 1.3.1 Info and Relationships](https://www.w3.org/TR/WCAG22/#info-and-relationships)

---

### Sequential headings (TXT-1-3)
Headings must be implemented sequentially in order without skipping levels. (for example: Heading 1, then Heading 2, then Heading 3 and so on). Headings of the same level may be repeated (for example: H2, H2, H2, etc.).

#### How to test
**Tool:** Accessibility Insights

1. Reveal headings via Accessibility Insights > Ad hoc tools > Headings.
2. View all headings and confirm that headings occur in sequential order without skipping levels. (for example: Heading 1, then Heading 2, then Heading 3 and so on, no skipping numbers).

#### Test outcomes
- **Pass**: Headings descend in single increments with no skipping.

- **Fail**: Headings do not descend in single increments and levels are skipped.

#### Related WCAG criteria
[WCAG 2.2 A - 1.3.2 Meaningful Sequence](https://www.w3.org/TR/WCAG22/#meaningful-sequence)

---

## Semantic markup (TXT-2)

### Group items with lists (TXT-2-1)
Groups of items (for example: a navigation menu or group of tabs) must be marked up as a list.

#### How to test
**Tool:** Browser Dev Tools (F12)

1. Locate any text content that is presented in a list format such as bulleted or numbered lists.
2. Locate any groups of items that should be marked up as lists (for example: a navigation menu or group of tabs).
3. Use the browser inspect feature to examine the HTML for these list components and confirm that they are properly marked up as lists.

#### Test outcomes
- **Pass**: All groups of items are marked as lists.

- **Fail**: All groups of items are not marked as lists.

- **NA**: No groups of items are present.

#### Related WCAG criteria
[WCAG 2.2 A - 1.3.1 Info and Relationships](https://www.w3.org/TR/WCAG22/#info-and-relationships)

---

## Logical order (TXT-3)

### Code order = logical content order (TXT-3-1)
The logical order of content must be present in the code order, allowing for successful use of the content when linearized and/or without CSS.

#### How to test
**Tool:** Web Accessibility Evaluation Toolbar (WAVE)

1. Open the WAVE tool with the page you are testing open in your browser.
2. Use the toggle switch to 'Disable styles'.
3. Confirm that the logical order of content is present in the code order.

#### Test outcomes
- **Pass**: The logical order of the content is followed.

- **Fail**: The logical order of the content is not followed.

#### Related WCAG criteria
[WCAG 2.2 A - 1.3.2 Meaningful Sequence](https://www.w3.org/TR/WCAG22/#meaningful-sequence)

---

## Non-sensory instructions (TXT-4)

### Instructions don't rely on sensory cues (TXT-4-1)
Instructions must never refer solely to sensory cues such as size, shape, color, sound, or spatial directions.

**Note:** When instructions refer to an interactive element, use the programmatic name of the element.

#### How to test
**Tool:** Visual inspection

1. Review any instruction text (on-screen and screen reader only).
2. Confirm that Instructions and interactions never refer solely to sensory cues such as size, shape, color, sound, or spatial directions.

#### Test outcomes
- **Pass**: Instructions and interactions never refer solely to sensory cues such as size, shape, color,  sound, or spatial directions.

- **Fail**: Instructions and interactions refer solely to sensory cues such as size, shape, color, sound, or spatial directions.

- **NA**: No instructions are present.

#### Related WCAG criteria
[WCAG 2.2 A - 1.3.3 Sensory Characteristics](https://www.w3.org/TR/WCAG22/#sensory-characteristics)

---

## Tables (TXT-5)

### No layout tables (TXT-5-1)
Tables must not be used for layout purposes. Layout tables are not a direct WCAG 2.2 AA failure, however when a table is linearized it can complicate or confuse the linear order of the content (See WCAG F49 for details).

#### How to test
**Tool:** ANDI

1. Run the ANDI tool on the page.
2. Locate any table elements identified by ANDI on the page.
3. Confirm that none of the tables are used for layout purposes.

#### Test outcomes
- **Pass**: Tables are not used for layout positioning; CSS is used instead.

- **Fail**: One or more layout table(s) is used.

#### Related WCAG criteria
[WCAG 2.2 A - 1.3.2 Meaningful Sequence](https://www.w3.org/TR/WCAG22/#meaningful-sequence)

---

### Markup tables (TXT-5-2)
All data tables must use THs and every TH must have scope="col" or "row" set unless any implied relationships would be untrue. In that case, headers= must be used to hard code how headers are read to users.

#### How to test
**Tool:** ANDI

1. Run the ANDI tool on the page.
2. Locate any table elements identified by ANDI on the page.
3. Confirm that `<th>` elements are used as appropriate and every `<th>` element has scope as appropriate. If present, confirm that headers point to the correct `<th>` elements' IDs.

#### Test outcomes
- **Pass**: Tables have correct `<th>` elements, `<td>` elements, and scope applied appropriately.

- **Fail**: One or more tables does not have correct `<th>` elements, `<td>` elements, and scope applied appropriately.

- **NA**: No tables are present.

#### Related WCAG criteria
[WCAG 2.2 A - 1.3.1 Info and Relationships](https://www.w3.org/TR/WCAG22/#info-and-relationships)

---

### Identify tables (TXT-5-3)
Data tables must be identified for screen readers by including the "title" of the table in its `<caption>` element, for example: "Transaction History for x2304".
 
**Note:** The caption may be hidden visually with CSS.

#### How to test
**Tool:** Screen reader

Bring up the list of tables (or cycle through each if a list is not available) with each supported screen reader and confirm that each table is identified.

#### Test outcomes
- **Pass**: All tables have titles that are read by the screen reader.

- **Fail**: One or more tables does not have a title that is read by the screen reader.

- **NA**: No tables are present.

#### Related WCAG criteria
[WCAG 2.2 A - 1.3.1 Info and Relationships](https://www.w3.org/TR/WCAG22/#info-and-relationships)

</Breakless>

---

# index

---
title: Visual design and multimedia
side_nav_title: Visual design and multimedia
description: Find visual design and multimedia requirements for testing web experiences.
side_nav_order: 4
---

<Breakless>

## Content resizing, styling, & reflow (VIS-1)

### Browser zoom usable (VIS-1-1)
Using the built-in browser functionality to zoom all page content to 200% (including text), all interactive content must remain fully usable.

#### How to test
**Tool:** System Settings

Use browser zoom to magnify your viewport to 200% and confirm that all interactive content remains fully usable.

#### Test outcomes
- **Pass**: All interactive content remains fully usable up to 200%.

- **Fail**: Some interactive content does not remain fully usable between 0 - 200%.

#### Related WCAG criteria
[WCAG 2.2 AA - 1.4.4 Resize Text](https://www.w3.org/TR/WCAG22/#resize-text)

---

### Content reflow (VIS-1-2)
Content remains functional and no information is lost when viewed at 320px width (for vertical scrolling content) or 256px height (for horizontal scrolling content). Scrolling in two directions must not be required.

Exception: two direction scrolling is allowed for elements that require it for usage such as:
- Data tables/charts
- Photos
- Maps

#### How to test
**Tool:** Browser Dev Tools (F12)

1. Use the browser dev tools/Inspector to set the page width to 320px for vertical scrolling content or 256px for horizontal scrolling content.
2. Confirm that all content remains functional and that no information is lost (for example: cut off text, missing UI, overlapping content).
3. Confirm that scrolling in two directions is not required.

Exceptions:
Horizontal scrolling is allowed for the following content:
- Data tables
- Photos
- Maps
- Charts
- Games
- UI with toolbars

#### Test outcomes
- **Pass**: Content remains functional and no information is lost when viewed at the required height or width. Scrolling in two directions is not required unless an element requires it for usage.

- **Fail**: Content is not functional or information is lost when viewed at the required height or width. Alternatively, scrolling in two directions is required.

- **NA**: Content is any of the following:
    - Data tables
    - Photos
    - Maps
    - Charts
    - Games
    - UI with toolbars

#### Related WCAG criteria
[WCAG 2.1 AA - 1.4.10 Reflow](https://www.w3.org/TR/WCAG22/#reflow)

---

### User text styling (VIS-1-3)
User text style settings do not cause a loss of content when:
- Line height (line spacing) is increased to at least 1.5 times the font size;
- Spacing following paragraphs is set to at least 2 times the font size;
- Letter spacing (tracking) is increased to at least 0.12 times the font size;
- Word spacing is set to at least 0.16 times the font size.

#### How to test
**Tool:** Text Spacing Bookmarklet

1. Load the page in the browser of your choice.
2. Run the Text Spacing Bookmarklet.
3. Perform a visual inspection of the content and confirm that there is not a resulting loss of content or meaning.

#### Test outcomes
- **Pass**: There is not a resulting loss of content or meaning when any of the four text spacing settings are changed.

- **Fail**: There is a loss of content or meaning when the four text spacing settings are changed.

#### Related WCAG criteria
[WCAG 2.1 AA -1.4.12 Text Spacing](https://www.w3.org/TR/WCAG22/#text-spacing)

---

## Color usage (VIS-2)

### Color contrast ratio (VIS-2-1)
A color contrast ratio of text, informational images, and images of text to their backgrounds must be at least 4.5:1, except if the text is 18pt or 14pt bold or larger, where a ratio of 3:1 is then required. Text that is part of a logo is not subject to this requirement.

If there is content that does not pass color contrast requirements, then an alternate (high-contrast) compliant style sheet must be available.

#### How to test
**Tool:** WebAIM Contrast Checker

Use a contrast analyzer to check color contrast ratio of text, and images of text to their backgrounds. Use the eye dropper tool to check any text that is missed by the automated scan. If a failure is identified with the automated scan which seems questionable use the eye dropper tool to double check. Contrast ratio must be at least 4.5:1, except if the text is 18pt or 14pt bold or larger, where a ratio of 3:1 is then required.

**Note:** All of this information will be provided in the contrast validation tool's side panel, except for text that is not HTML text or an HTML colored background (for example: text over a gradient image). In this case, use the color picker tool from the panel to pick samples and determine if the text fails in any places.

If there is content that does not pass color contrast requirements, then an alternate (high-contrast) compliant style sheet must be available.

#### Test outcomes
- **Pass**: All text meets expected minimum contrast ratio.

- **Fail**: All text does not meet the expected minimum contrast ratio and an alternate style sheet is not provided.

- **NA**: Text is part of an inactive user interface component or pure decoration.

#### Related WCAG criteria
[WCAG 2.2 AA - 1.4.3 Contrast (Minimum)](https://www.w3.org/TR/WCAG22/#contrast-minimum)

---

### Contrast for non-text UI components (VIS-2-2)
User interface components and graphical objects must have a contrast ration of at least 3:1 against adjacent colors. 

#### How to test
**Tool:** WebAIM Contrast Checker

Confirm that all user interface components and graphical objects have a contrast ratio of at least 3:1 against adjacent colors including the background and other non-text objects by using the eye dropper tool in a contrast analyzer.

#### Test outcomes
- **Pass**: All user interface components and graphical objects have a contrast ratio of 3:1 against adjacent colors.

- **Fail**: Some user interface components and/or graphical objects do not have a contrast ratio of 3:1 against adjacent colors.

#### Related WCAG criteria
[WCAG 2.1 AA - 1.4.11 Non-text Contrast](https://www.w3.org/TR/WCAG22/#non-text-contrast)

---

### Support high contrast (VIS-2-3)
All content adapts and supports the user's high contrast theme settings

#### How to test
**Tool:** System Settings

Windows: Use the search feature to search for Contrast Themes. Activate the high contrast themes from the settings window.
Mac: Go to System Preferences>Accessibility>Display>Invert Colors.

#### Test outcomes
- **Pass**: All content supports high contrast themes.

- **Fail**: Some content does not support high contrast themes.

#### Related WCAG criteria
- [WCAG 2.1 – 4.1 Compatible](https://www.w3.org/TR/WCAG22/#compatible)
- [Section 508 302.2 With Limited Vision](https://www.access-board.gov/guidelines-and-standards/communications-and-it/about-the-ict-refresh/final-rule/text-of-the-standards-and-guidelines#302-functional-performance-criteria)
- [Section 508 302.3 Without Perception of Color](https://www.access-board.gov/guidelines-and-standards/communications-and-it/about-the-ict-refresh/final-rule/text-of-the-standards-and-guidelines#302-functional-performance-criteria)
- [Section 508 502.2.2 No Disruption of Accessibility Features](https://www.access-board.gov/guidelines-and-standards/communications-and-it/about-the-ict-refresh/final-rule/text-of-the-standards-and-guidelines#502-interoperability-assistive-technology)

---

### Not only color (VIS-2-4)
If a color difference is used to convey information, that information must also be available in text or through some other alternative method.
Link text may be distinguished from static text through use of color as long as the following are true:
- A 3:1 contrast ratio difference exists between the link text and other static text
- A visual indicator is provided when the link receives focus (for example: visible underline on hover and keyboard focus)

#### How to test
**Tool:** Visual inspection

1. Perform a visual inspection of the page.
2. Confirm that whenever a difference in color is used to convey information, that information is also be available in text or through some other alternative method.

#### Test outcomes
- **Pass**: A non-color alternative is presented along with color.

- **Fail**: Only color is used to indicate meaning.

- **NA**: Color is not used to convey meaning.

#### Related WCAG criteria
[WCAG 2.2 A - 1.4.1 Use of Color](https://www.w3.org/TR/WCAG22/#use-of-color)

---

## Images (VIS-3)

### Text alternatives (VIS-3-1)
All non-text content must provide text alternatives that provide equivalent information, context, and purpose to the user using the following techniques (as applicable):
- For `<img>` elements, provide the text alternative using the alt attribute
- For other non-text content (for example: `role=&quot;img&quot;`), aria-label/labelledby, or visibly hidden textaria-label/labelledby, or visibly hidden text
- For decorative `<img>` elements, provide `alt=&quot;&quot;` (alt null)
- For other decorative non-text content, `aria-hidden=&quot;true&quot;`

#### How to test
**Tool:** Accessibility Insights

Using Accessibility Insights, confirm that all non-text content provides text alternatives that provide equivalent information, context, and purpose to the user and that decorative non-text content is appropriately hidden using null alternative text or `aria-hidden=&quot;true&quot;`

#### Test outcomes
- **Pass**: All non-text content provides text alternatives and all decorative content is hidden correctly.

- **Fail**: Some non-text content does not have text alternatives or some decorative content is not hidden correctly.

- **NA**: Non-text content is not present.

#### Related WCAG criteria
[WCAG 2.2 A - 1.1.1 Non-text Content](https://www.w3.org/TR/WCAG22/#non-text-content)

---

### No images of text (VIS-3-2)
Text must always be presented using live text and CSS rather than an image of text, except for logos and within pictures where it cannot be avoided (for example: graphs or screenshots).

#### How to test
Using the mouse, click and drag over all text on the page to select it.
HTML text will be selectable. Text that is part of an image will show the entire image being highlighted.
Confirm that text is presented using text rather than in an image of text, except for logos and within pictures where it cannot be avoided (for example: graphs or screenshots).

#### Test outcomes
- **Pass**:Images of text are not used.

- **Fail**: Images of text are used.

#### Related WCAG criteria
[WCAG 2.2 AA - 1.4.5 Images of Text](https://www.w3.org/TR/WCAG22/#images-of-text)

---

## Multimedia (VIS-4)

### Captions (prerecorded) (VIS-4-1)
Captions are available for content with both audio and video, except when the content is an alternative for text and is clearly labeled as such.

#### How to test
**Tool:** Visual inspection

1. Identify prerecorded content with both audio and video.
2. Confirm that captions are available.
3. Confirm the captions contain all audio information (for example: speech, sound effects, music, etc.).

#### Test outcomes
- **Pass**: All prerecorded content with both audio and video has accurate captions.

- **Fail**: Any prerecorded content with both audio and video does not have captions, or the captions do not contain all audio information.

- **NA**: No prerecorded content with both audio and video exists.

#### Related WCAG criteria
[WCAG 2.2 A - 1.2.2 Captions (Prerecorded)](https://www.w3.org/TR/WCAG22/#captions-prerecorded)

---

### Audio description or media alternative (prerecorded) (VIS-4-2)
A transcript or audio description is available for content with both audio and video, except when the content is an alternative for text and is clearly labeled as such.

#### How to test
**Tool:** Visual inspection

1. Test “Audio Description (Prerecorded) VIS-4-4”.
2. If "Audio Description (Prerecorded) VIS-4-4" passes, this also passes.
3. If "Audio Description (Prerecorded) VIS-4-4" fails, confirm a transcript exists that describes the meaningful visual information.

#### Test outcomes
- **Pass**: "Audio Description (Prerecorded) VIS-4-4" is passing.
or
A transcript is available that describes all meaningful information.

- **Fail**: Neither a transcript or audio description is available and there is meaningful information not described by the audio.

- **NA**: No content with both audio and video exists.
or
The exception is met.

#### Related WCAG criteria
[WCAG 2.2 A - 1.2.3 Audio Description or Media Alternative (Prerecorded)](https://www.w3.org/TR/WCAG22/#audio-description-or-media-alternative-prerecorded)

---

### Captions (live) (VIS-4-3)
Captions must be available for live content with both audio and video.

#### How to test
**Tool:** Visual inspection

1. Identify live content with both audio and video.
2. Confirm that captions are available.
3. Confirm the captions contain all audio information (for example: speech, sound effects, music, etc.).

#### Test outcomes
- **Pass**: All live content with both audio and video has captions.

- **Fail**: Any live content with both audio and video does not have captions or the captions do not contain all of the audio information.

- **NA**: No live content with both audio and video exists.

#### Related WCAG criteria
[WCAG 2.2 AA - 1.2.4 Captions (Live)](https://www.w3.org/TR/WCAG22/#captions-live)

---

### Audio description (prerecorded) (VIS-4-4)
An audio description track must be available if there is meaningful visual information that is not included in the audio track for prerecorded content with both audio and video.

#### How to test
**Tool:** Visual inspection

1. Identify prerecorded content with both audio and video.
2. If the content provides meaningful visual information that is not described by the audio, confirm it also includes an audio description track that explains the visual information.

#### Test outcomes
- **Pass**: Audio description is available when needed.

- **Fail**: Meaningful visual information in the video is not described by the audio and an audio description track is missing, incomplete, or inaccurate.

- **NA**: The audio describes the visual content.
or
There is no prerecorded content with both audio and video.

#### Related WCAG criteria
[WCAG 2.2 AA - 1.2.5 Audio Description (Prerecorded)](https://www.w3.org/TR/WCAG22/#audio-description-prerecorded)

---

### Transcripts for audio-only/video-only (VIS-4-5)
For audio-only and video-only media, a transcript must be provided which provides the same information as presented in the original media content.

#### How to test
**Tool:** Visual inspection

A transcript which provides the same information as presented in the original media content must be made available for all audio-only and/or video-only content.

#### Test outcomes
- **Pass**: Transcripts are provided.

- **Fail**: Transcripts are not provided.

- **NA**: No audio or video only content is present.

#### Related WCAG criteria
[WCAG 2.2 A - 1.2.1 Audio-only & Video-only (Prerecorded)](https://www.w3.org/TR/WCAG22/#audio-only-and-video-only-prerecorded)

</Breakless>

---

# index

---
title: Address
tab_title: Usage
description: Groups of input or text fields that collect address details from users.
meta_description: Learn how to implement groups of input or text fields that collect address details from users.
thumbnail: assets/components/address-graphic.svg
keywords: ["Address country code", "country selection", "address state abbreviations", "billing address", "mailing address", "shipping address"]
related:
  components:
    - combobox
    - input
  patterns:
    - forms
---

The address pattern is a set of [input](https://design.visa.com/components/input) fields intuitively laid out to collect address information. Users can enter their name, country, street address, city, state, ZIP code, country code, and phone number information.<br/><br/>
Also known as: Address country code, country selection, address state abbreviations, billing address, mailing address, shipping address.

## Anatomy

<img src="https://design.visa.com/assets/components/address/address-anatomy.svg" alt="An address form example with letters pointing to different sections. A is pointing to a First name text input and last name text input. B is a Country combo box. C is an Address text input and an Apartment, suite, etc text input. D is a City text input, State combo box, and Zip code text input. E is a Country code combo box and F is a Phone number text input. All but the second Address input have * in the labels."/>

**A. Name fields (required):** Text input field for first name and last name to be entered in separate fields.<br/>
**B. Country field (required):** Combobox input field for country selection.<br/>
**C. Address field (required):** Text input field for address entry. The second address line is optional.<br/>
**D. City, State, and ZIP code fields (required):** Text input fields for City, State and ZIP code entry.<br/>
**E. Country code field (required):** Combobox input field for country code entry.<br/>
**F. Phone number field (required):** Numeric input field for phone number entry.

## Usage

When to use and when not to use address pattern

- When to use: When user’s address information needs to be collected.
- When not to use: In cases where the user’s address isn’t necessary or the application requires minimal data collection.

## Best practices
- Follow all guidelines found in [Input](https://design.visa.com/components/input) and [Combobox](https://design.visa.com/components/combobox) when implementing those items in the address pattern.
- Match address information to local region expectations whenever possible.

### Familiar formatting
Display content in a format that’s familiar and intuitive to users. Aim to reflect the pattern that the information is usually presented in for that region to make it easier for users to understand the content. Some fields such as postal code or phone number may include text formatting. The order that these fields appear may also be different from the provided layout. Make sure to use the correct labels and address form fields to increase form success.

#### Name order

In some regions, the last name should be the first field in this set. If this is a billing address, the name should match the name of the registered card holder. Check with your product team and the US Office of Foreign Assets Control (OFAC) for specific business requirements.

<img src="https://design.visa.com/assets/components/address/address-bp-name.svg" alt="Two examples of first and last name fields. The North America example has the first name field above the last name field. The Japan example has Last name above first name."/>

## Behaviors

### Autosuggest

Each region and locale should have an optimized address format, which may be adjusted based on country selection. Autosuggest provides a list of suggested addresses as the user types. The suggestions typically come from a database of known addresses, and the user can select the correct one from the list. This helps in reducing user errors and speeds up the process of filling out the form. Learn more about Autosuggest in [Input](https://design.visa.com/components/input).

### Autocomplete

Enable autocomplete of the rest of the address fields (such as city, state, and ZIP code) once the user completes typing or selects an address from the autosuggest list. Allow free-form input in the main fields in case there are unregistered addresses.

<img src="https://design.visa.com/assets/components/address/address-behaviors-autocomplete.svg" alt="An address combo box with 100 Main entered in the text field. Below the field is a menu of options."/>

### States and provinces

The user selects their state using a combobox. Refer to the [Full menu with automatic selection](https://design.visa.com/components/combobox/usage#automatic-selection) section in the combobox guidelines for complete keyboard and interaction behavior and guidance on autocomplete functionality.

         
          #### Shortened field width
            The shortened width of the field sets user expectations for entering the abbreviation instead of the full name of the state. The list of options will be in alphabetical order. 
            <img src="https://design.visa.com/assets/components/address/address-behaviors-default.svg" alt="An expanded state combo box with California entered and highlighted in the text input. The visible options are AL, AK, AZ, and AR"/>
      
         
          #### Typed input
            As the user types, highlight in the menu moves to the first matching item. When the user hits enter, the item will be selected. 
          <img src="https://design.visa.com/assets/components/address/address-behaviors-typed.svg" alt="A collapsed state combo box. AK is entered into the text input"/>      
      

         
          #### Reopening the field

            When reopened, the menu shows the selected item in the context of the full list of menu items.
            <img src="https://design.visa.com/assets/components/address/address-behaviors-selected.svg" alt="An expanded state combo box with the typed AK text highlighted and a list of options below including AK."/>
      
         
          #### Error prevention

            Invalid entries won't be automatically selected. Upon exiting the field, it resets to the last valid entry or its default state. 
           <img src="https://design.visa.com/assets/components/address/address-behaviors-error.svg" alt="An expanded state combo box with the typed AA text highlighted and a list of options below in alphabetical order."/>      
      

### Country code and phone number

The country code field includes a combobox and can be selected by entering the country code or country name. The phone number field is a numeric input field. This field may include formatting with an area code parentheses, spaces, and dashes.

<img src="https://design.visa.com/assets/components/address/address-bp-countrycode.svg" alt="An expanded Country code combo box with +1 highlighted in the input field and an options list including +54 Argentina and +61 Australia. A phone number text input is to the right with the value (510) 388-6105"/>

## Content
- Write all content in sentence case, except for proper nouns.
- Follow guidance in [Forms](https://design.visa.com/patterns/forms) when writing form titles, field labels, and inline messages.

### Labels
- Limit labels to a few brief words.
- Ensure labels accurately represent the expected input to reduce errors.
- Use parallel structure across labels, using either nouns like “Email” or verbs like “Enter email”.

#### Inline messages
- Limit all inline messages (including errors) to one to two short sentences with punctuation.
- Use inline messages to provide additional guidance such as format or specific syntax or values to help avoid errors.
- Provide concise, descriptive, and helpful guidance about the field’s usage and necessity, avoiding technical jargon.

#### Inline error messages
- Use inline error messages to draw attention and to errors without causing frustration.
- Provide clear, prescriptive guidance on correcting the error. Avoid redirecting users to another page to fix it.
- Communicate whether the problem can occur again and offer an alternative backup solution in case it does.


---

# accessibility

---
title: Application layouts
description: Learn how to choose a navigational frame based on page content and information architecture.
meta_description: Find the right navigational frame for your project based on page content and information architecture.
thumbnail: assets/patterns/application-layouts/layouts.svg
tab_order: 2
---

Creating access for everyone, everywhere requires attention to accessibility attributes, best practices, and requirements. Find accessibility guidance below.

## Best practices 

### Landmarks
Each page needs landmark regions, such as, main (which is required), header, and footer. These areas help keyboard users to easily navigate a page. Each landmark needs an accessible name, particularly if there’s more than one of them. For example, if there are two `<nav>` elements, each needs a unique name. <br></br> An accessible name is optional for some elements which appear once per page, like `<main>` and [footer](https://design.visa.com/components/footer/usage). All page content must be contained within a landmark region. 

- Don’t include the landmark role type (such as "main," "banner," "navigation," or "contentinfo") in the accessible name because this will already be announced by the screen reader.
- Include a “Skip to main content” link as the first interactive element on every page (or as the second if a “Skip to login” link is present). This link moves focus directly to the main content region, or to the errors summary if present. It may be visually hidden until it receives keyboard focus.
- Place global UI elements consistently throughout your application, not inside the `<main>` element, so users can easily find them.
- Don’t include more than one `<header>` or `role='banner'`.
- Each screen should have exactly one `<main>` region. This is the primary content area of the page.
- Each screen should have exactly one `<h1>` heading, which should closely match the title attribute in the `<head>`section. This includes single page apps (SPA). The heading text and head title should change each time the user visits a new page.
- Include only one [footer](https://design.visa.com/components/footer/usage).
- Ensure each `<nav>`  has a unique accessible name.
- Ensure each `<iframe>`  has an accessible name.

### Scroll and zoom
The user should be able to reach every item on the page. Ensure elements fixed to the viewport can be scrolled and don't block other parts of the page, especially when zoomed. It's recommended to have either a fixed header or a fixed footer, not both, because zooming the page can leave little or no scrollable content area. <br/><br/> 
Some elements such as tables may be wider than what fits in the layout. It's recommended to allow horizontal scroll on those elements or their immediate containers rather than allowing horizontal scroll on the whole page.

### Logical tab order 
Keyboard navigation through the page should be logical and useful. Each section's order in the DOM, tab order, and visual order should all be in agreement.



---

# index

---
title: Application layouts
description: Learn how to choose a navigational frame based on page content and information architecture.
meta_description: Learn how to choose a navigational frame based on page content and information architecture.
page_size: full-width
thumbnail: assets/patterns/application-layouts/layouts.svg
tab_title: Code
show_table_of_contents: false
examples:
  - slug: "horizontal"
    title: "Horizontal application layouts"
  - slug: "stacked-horizontal"
    title: "Stacked horizontal application layouts"
  - slug: "mixed"
    title: "Mixed application layouts"
  - slug: "vertical"
    title: "Vertical application layouts"
---

<LibraryCardListLarge>
    <LibraryCardLarge 
        title="Horizontal application layouts" 
        description="Layouts with horizontal navigation above the main content area."
        href={`https://design.visa.com/patterns/application-layouts/horizontal`} 
        thumbnail={`https://design.visa.com/assets/patterns/application-layouts/layout-horizontal-graphic.svg`}
        hasChevron
        hoverColor={colorGreen}
    />
    <LibraryCardLarge 
        title="Stacked horizontal application layouts" 
        description="Layouts with stacked horizontal navigation above the main content area."
        href={`https://design.visa.com/patterns/application-layouts/stacked-horizontal`} 
        thumbnail={`https://design.visa.com/assets/patterns/application-layouts/layout-horizontal-stacked-graphic.svg`}
        aria-label={"Color palettes (internal only, opens in new tab)"}
        hasChevron
        hoverColor={colorGreen}
    />
    <LibraryCardLarge 
        title="Mixed application layouts" 
        description="Layouts that combine both horizontal and vertical navigation with a central content area."
        href={`https://design.visa.com/patterns/application-layouts/mixed`} 
        thumbnail={`https://design.visa.com/assets/patterns/application-layouts/layout-mixed-graphic.svg`}
        hasChevron
        hoverColor={colorGreen}
    />
    <LibraryCardLarge 
        title="Vertical application layouts" 
        description="Layouts with vertical navigation beside the main content area."
        href={`https://design.visa.com/patterns/application-layouts/vertical`} 
        thumbnail={`https://design.visa.com/assets/patterns/application-layouts/layout-vertical-graphic.svg`}
        hasChevron
        hoverColor={colorGreen}
    />
</LibraryCardListLarge>


---

# usage

---
title: Application layouts
tab_title: Usage
tab_order: 1
description: Learn how to choose a navigational frame based on page content and information architecture.
meta_description: Find the right navigational frame for your project based on page content and information architecture.
thumbnail: assets/patterns/application-layouts/layouts.svg
keywords: ["application layouts", "navigation", "responsive grid system", "content area", "templates"]
related: 
  components: 
    - footer
    - horizontal-navigation
    - vertical-navigation
  baseElements:
    - responsive-grid-system
---

An application layout consists of a navigational frame and a content area organized within a [Responsive grid system](https://design.visa.com/base-elements/responsive-grid-system). It provides a foundational framework to establish consistency throughout a product experience, and serves as a key starting point for designers and developers.

## Best practices
- Start with the pre-built layouts in our component library and adjust as needed. 
- Use layouts to establish default positioning for panels, forms, and messaging components and toggle their visibility to fit your application. 
- Customize navigation styles, color palettes, and background colors as needed.
- Select the appropriate layout variants to accommodate different page widths and content area layouts.
<br/>
**Note:** To use the VPDS grid system, add the Components library to your Figma project, then navigate to Layout guide in the Properties panel.

## Navigational frames
VPDS supports four main navigational frames: horizontal, stacked horizontal, vertical, and mixed.

         
          ### Horizontal navigation
          <Typography variant="body-2"> [Horizontal navigation](https://design.visa.com/components/horizontal-navigation/usage) is the most common way of displaying the top-level pages of a site. It’s typically placed at the top of the page and occupies horizontal space directly above the main content area.</Typography>
            <img src="https://design.visa.com/assets/patterns/application-layouts/layouts-nav-horizontal.svg" alt="Web screen with horizontal navigation bar"/>
      
         
          ### Stacked horizontal navigation
          <Typography variant="body-2"> [Stacked horizontal navigation](https://design.visa.com/components/horizontal-navigation/usage#stacked-horizontal-navigation) adds a secondary navigation bar under the primary horizontal bar. This works best for applications with a larger number of main navigation items to help declutter the experience.</Typography>
            <img src="https://design.visa.com/assets/patterns/application-layouts/layouts-nav-advanced.svg" alt="Web screen with a horizontal navigation bar and horizontal subnav"/>
      

          
          ### Vertical navigation
          <Typography variant="body-2"> [Vertical navigation](https://design.visa.com/components/vertical-navigation/usage) is located next to the main content area on the page, and can be used when a website has a large number of navigation items or when horizontal space is limited.</Typography>
            <img src="https://design.visa.com/assets/patterns/application-layouts/layouts-nav-vertical.svg" alt="Web screen with vertical navigation bar"/>
      
         
          ### Mixed navigation
          
          Mixed navigation combines horizontal and vertical navigation in complex applications. The horizontal bar has global navigation items, while the vertical panel has local navigation items.
            <img src="https://design.visa.com/assets/patterns/application-layouts/layouts-nav-mixed.svg" alt="Web screen with horizontal and vertical navigation bars"/>
      

## Grid systems
Each layout uses a responsive grid system that can adjust to different screen sizes. The grid changes depending on which panels are included, such as navigation or information sections, so it fits the layout and page width. For example, the grid designed for vertical and mixed layouts adapts to accommodate the left navigation panel. Learn more about grid systems in [Responsive grid system](https://design.visa.com/base-elements/responsive-grid-system).<br/>

### Content areas

A content area is the primary section of the interface where the main information, features, and interactive elements of an application are displayed. Content areas can span multiple columns, and information should be displayed in a logical order based on the intended user flow.<br/><br/>
Content areas reflow and adapt to varying page widths and breakpoints. When working on a responsive design, consider how the content areas will shift as the page grows and shrinks, and communicate intentions for this reflow with your development team.
<img src="https://design.visa.com/assets/patterns/application-layouts/layouts-grid.svg" alt="Web page highlighting the center content area and the side page margins."/>

**A. Margins:** White space along the edges of the screen that ensures content doesn’t get cut off.<br/>**B. Content area:** Space available for content to occupy once margins have been defined.

## Platform considerations

### Mobile

For mobile experiences, 375px is a common reference width. However, actual screen widths vary across devices, so layouts should be designed responsively to accommodate different sizes.
<img src="https://design.visa.com/assets/patterns/application-layouts/layouts-platform-mobile.svg" alt="A mobile top app bar that shows hamburger menu, logo, utility icons, and tab bar."/>

### Tablet

For tablet experiences, 768px is a common reference width.  However, actual screen widths vary across devices, so layouts should be designed responsively to accommodate different sizes.
<img src="https://design.visa.com/assets/patterns/application-layouts/layouts-platform-tablet.svg" alt="Tablet top app bar and tab bar"/>

### Ultra wide screen views

There are fixed and fluid grid options for use cases where the screen size is 1600px or greater. Keep in mind how your content areas will shift as the page grows and shrinks, and communicate the intended experience with your development team. Learn more about fixed and fluid grid options in [Responsive grid design](https://design.visa.com/base-elements/responsive-grid-system).
<img src="https://design.visa.com/assets/patterns/application-layouts/layouts-platform-wide.svg" alt="Ultra wide screen with a horizontal nav bar"/>


---

# index

---
title: Card input
tab_title: Usage
description: Sets of input fields that allow users to enter payment information.
meta_description: Learn how to use sets of input fields that allow users to enter payment information.
thumbnail: assets/components/card-input-graphic.svg
keywords: ["Card number entry"]
related:
  components:
    - input
    - select
---

The card input pattern is a set of [input](https://design.visa.com/components/input) and [select](https://design.visa.com/components/select) components intuitively laid out for users to enter their payment information.<br/><br/>
Also known as: Card number entry.

## Anatomy

<img src="https://design.visa.com/assets/components/card-input/cardinput-anatomy.svg" alt="A card input form example with letters pointing to different sections. A is pointing to a long Card number text input field that is filled in with a 16-digit card number. B is pointing to a Visa logo on the right side of the card input field. C is pointing to a label that says Expires (MM/YY). Underneath this are two comboboxes, one for month and one for year. In between the field is a / character. D is pointing to an icon to the right of a security code text input field that is an I in a small blue circle."/>

**A. Card number field (required):** Numeric input field for card number entry.<br/>
**B. Trailing icon (required):** Displays the generic card icon or network indicator when the card number field is in focus.<br/>
**C. Expiration date fields (required):** Select fields for card expiration month and year entry.<br/>
**D. Security code field (required):** Numeric input field for security code entry that should be hidden upon user entry.<br/>
**E. Security code information icon (required):** Icon displaying important information about the security code when selected.

## Usage

When to use and when not to use the card input pattern

- When to use: If the website or application doesn’t have the necessary security measures in place to process and store user’s card information.<br/><br/> If a payment isn’t actually being processed and card information is only being inputted for information collection purposes (i.e. account validation).

## Best practices
- Follow guidance found in [Input](https://design.visa.com/components/input) and [Select (native)](https://design.visa.com/components/select) when implementing those items in the card input pattern.
- Ensure date formatting aligns with the user’s region when possible.

## Behaviors

### Card number field

#### Card number focus state

When the focus is on the card number field, the generic card icon will appear in the trailing position.

<img src="https://design.visa.com/assets/components/card-input/cardinput-behaviors-card-1.svg" alt="A focused card number text field with an active cursor and generic card icon shown"/>

         
          #### Network indicator

            The network indicator appears when the field is in focus and  the network has been detected based on the first three digits. 
            <img src="https://design.visa.com/assets/components/card-input/cardinput-behaviors-card-2.svg" alt="A focused card number field with three digits typed and a visible Visa logo."/>
      
         
          #### Auto-formatting

            The card number is autoformatted with spacing to match the network. Reference [Recognizing the network](https://design.visa.com/patterns/card-input#recognizing-the-network) below for details on how autoformatting occurs. 
          <img src="https://design.visa.com/assets/components/card-input/cardinput-behaviors-card-3.svg" alt="A Card number field filled in with a 16-digit number with extra spacing between each set of 4 numbers."/>      
      

<Typography id="recognizing-the-network" tag="h4" variant="subtitle-1">Recognizing the network</Typography>

Setting up card input fields to recognize and adapt to the specific patterns associated with different card networks helps to improve the user experience and reduce input errors. Implement autoformatting to automatically add spaces or dashes as users type their card numbers. This makes the input process smoother and aligns the user input with the visual formatting of their physical cards. For example, Visa and Mastercard typically use a 4-4-4-4 spacing pattern, whereas American Express uses a 4-6-5 pattern.<br/><br/>
The first few digits of a card number, known as the Issuer Identification Number (IIN), can identify the card network. Your application can recognize these early in the input process and adjust the field to match the expected format for that network.

Card network length, spacing, and IIN ranges

- Card network: 13, 16, 19
- Length: 4
- IIN ranges: #### #### #### #### (4-4-4-4)

- Card network: 16
- Length: 51-55<br/>222100-272099
- IIN ranges: #### #### #### #### (4-4-4-4)

- Card network: 12-19
- Length: 500000-509999,<br/>560000-589999,<br/>600000-699999
- IIN ranges: #### #### ##### (4-4-5)<br/><br/> #### ###### ##### (4-6-5)<br/><br/>#### #### #### #### (4-4-4-4)<br/><br/>#### #### #### #### ### (4-4-4-4-3)

- Card network: 15
- Length: 34, 37
- IIN ranges: #### ###### ##### (4-6-5)

- Card network: 16, 19
- Length: 6011,<br/>622126‑622925,<br/>644‑649, 65
- IIN ranges: #### #### #### #### (4-4-4-4)

- Card network: 16
- Length: #### #### #### #### (4-4-4-4)

### Expiration date

The set should be labeled “Expires (MM/YY)” to match the credit card formatting. The slash symbol (/) is placed between the two select fields to align with the visual formatting of physical cards. While the contents are relatively short, the larger width of the form fields accommodate better placement for error message content, especially for localization.
- Don’t give users the option to select an expiration date combination that occurs in the past.
- Enable users to type, jump to an option and select it without having to open the menu. 
- Don't automatically add or guess missing numbers for the month or year if the user doesn't enter the full amount.

         
          #### Expiration month

            <img src="https://design.visa.com/assets/components/card-input/cardinput-behaviors-expiration-month.svg" alt="An expanded Month expiration date combo box. The options shown are 01, 02, 03, etc."/>
            - Display all 12 months in the MM format and list them in the menu options. 
      
         
          #### Expiration year

          <img src="https://design.visa.com/assets/components/card-input/cardinput-behaviors-expiration-year.svg" alt="An expanded year expiration date combo box. The options shown are 23, 24, 25, etc."/> 
          - Display the present year and following 19 years after for a total of 20 years in the YY format.      
      

### Security code
The number of digits required in the security code, three or four digits, is determined by the card’s IIN. 

#### Filled state

The security code should be hidden as it’s being typed in so onlookers can’t read the characters. 

<img src="https://design.visa.com/assets/components/card-input/cardinput-behaviors-security-filled.svg" alt="Security code text input filled in with three dots representing the hidden numbers"/>

#### Security code icon button

Selecting this icon shows users more information about where to find the security code on their physical card. Upon expansion/collapse, the screen reader will announce “expanded” or “collapsed”, respectively. When users move the focus to the content, the screen reader will also announce the content of the disclosure. Most security codes are three digits, however American Express has four. 

<img src="https://design.visa.com/assets/components/card-input/cardinput-behaviors-security-icon.svg" alt="Empty security code text field. Below is a small icon of a card with the security code enlarged next to text that says Security code, the 3-digit code on the back of your card."/>

## Content
- Write all content in sentence case, except for proper nouns.
- Follow guidance in [Forms](https://design.visa.com/patterns/forms) when writing form titles, field labels, and inline messages.
- Follow guidance found in [Messaging](https://design.visa.com/content/messaging) when crafting error messages.

### Labels

- Limit labels to a few brief words.
- Ensure labels accurately represent the expected input to reduce errors.
- Use parallel structure across labels, using either nouns like “Email” or verbs like “Enter email”.

### Inline messages

- Limit all inline messages (including errors) to one to two short sentences with punctuation.
- Use inline messages to provide additional guidance such as format or specific syntax or values to help avoid errors.
- Provide concise, descriptive, and helpful guidance about the field’s usage and necessity, avoiding technical jargon.

### Inline error messages

- Use inline error messages to draw attention and to errors without causing frustration.
- Provide clear, prescriptive guidance on correcting the error. Avoid redirecting users to another page to fix it.

#### Card number errors

When users enter an invalid card number, an incomplete number or don’t fill in the field at all,  communicate using inline error messages to suggest how users can correct the field.<br/><br/>
In situations where the card brand has been identified, but the number doesn’t align to the IIN pattern, be specific about asking the user to review the card number entered. For example, “Please check the Visa card number you entered.”

<img src="https://design.visa.com/assets/components/card-input/card-input-content-card-number.svg" alt="Card number text field outlined in red with an error message reading: Please enter a valid card number"/>

#### Expiration date errors

When the user only fills one field, the empty field should have a corresponding error message. Use one message when both fields aren’t filled out.

<img src="https://design.visa.com/assets/components/card-input/card-input-content-expiration-1.svg" alt="Expiration date field with month field outlined in red with an error message reading: Please enter the expiration month. To the right of it is an example of the expiration date field with year field outlined in red with an error message reading: Please enter the expiration year."/>

<img src="https://design.visa.com/assets/components/card-input/card-input-content-expiration-2.svg" alt="Expiration date field with month and year fields outlined in red with an error message reading: Please enter the card expiration date."/>

#### Security code errors

When the user doesn’t enter the security code or enters an incomplete value, communicate to the user that they need to enter a valid security code. When possible, let the user know how they can fix the error, for example, if they user enters four digits when they need to enter only three.

<img src="https://design.visa.com/assets/components/card-input/card-input-content-security.svg" alt="Security code field outlined in red with an error message reading: Please enter a valid security code."/>


---

# accessibility

---
title: Chat
tab_title: Accessibility
description: Interfaces that enable users to conduct conversations with human and AI assistants.
meta_description: Learn how to design chat interfaces that enable users to conduct conversations with human and AI assistants.
thumbnail: assets/patterns/chat-graphic.svg
tab_order: 2
---

## Best practices

- Use headings and proper structural elements to organize the chat interface and help users navigate efficiently.
- Avoid moving focus automatically as it can be disorienting for some users. Let users navigate at their own pace.
- Make your chat interface consistent with common chat implementations to improve learnability and usability.
- Provide fast‑navigation controls such as a visible button and optional keyboard shortcut that allows users to quickly jump to important messages in the chat, such as the most recent reply or the next unread message. These controls must not replace standard navigation and should follow accessibility and conflict‑avoidance guidelines.
- Use off-screen text to announce new messages or indicate other changes in the chat state for screen reader users.
- Use landmarks such as aside and headings `<h2>`, `<h3>`, etc. Ensure the headings are in hierarchical order. 
- Use `role=“alert”`, `role=“status”`, or `aria-live` to announce new messages.

### Screen readers
Screen readers use different modes to read different kinds of content. One mode lets users tab from one actionable item to another using the Tab key. In this mode, a user should be able to tab to each chat bubble.  Another mode lets users read regular, non-actionable text using a combination of keys including the arrow keys. The exact key combination for this mode varies by device, browser, and user settings.

<br/>
Landmarks and headings help screen reader users quickly navigate and scan a page. People who rely on screen readers don’t just read the page from top to bottom, they can pull up a list of headings and landmarks to get a sense of the page and jump to the items they want.

<br/>
Communicating incoming messages is to a screen reader is a common challenge because a message might be split into multiple parts. Screen readers react to the browser, so there will always be some lag between the visual chat and the screen reader. Keep in mind that many people who rely on screen readers have them set to read very quickly.

### Sender identification
If there are two or more people in a chat, the sender needs to be announced. The sender should always be identified as part of each chat bubble, but it’s crucial to announce when there are multiple people in the chat. Even if the chat is between the user and AI, the user still needs to be able to navigate back to their own messages, which need to be identified as theirs, because the user might not remember what they asked or who said what.

### Chat announcements
Each chat announcement, even polite ones, interrupts the user experience and can be disruptive. Consider how the chat is used in your experience and aim to minimize disruption for the user. For example, in a full-page chat interface, users are focused on the conversation, so announcements about new message are less likely to cause issues. However, for a chat that’s a secondary part of a larger page, like a help chat in the corner, frequent announcements are potentially more distracting to the user’s main task on the page.

## Keyboard controls
Keyboard actions and their corresponding behaviors for accordion

- Key: Prompts the action associated with the focused interactive element.

- Key: Moves keyboard focus to the next interactive element in the chat.

- Key: Moves keyboard focus to the previous interactive element in the chat.

<br/>
<Typography>Note: Keyboard shortcuts commonly used for editing text should be maintained unless uniquely specified.</Typography>



---

# index

---
title: Chat
description: Interfaces that enable users to conduct conversations with human and AI assistants.
meta_description: Learn how to design chat interfaces that enable users to conduct conversations with human and AI assistants.
page_size: full-width
thumbnail: assets/patterns/chat-graphic.svg
tab_title: Code
show_table_of_contents: false
examples:
  - slug: 'full-page-chat'
    title: 'Full-page chat'
  - slug: 'dialog-chat'
    title: 'Dialog chat'
  - slug: 'panel-chat'
    title: 'Panel chat'
---

<LibraryCardListLarge>
    <LibraryCardLarge 
        title="Full-page chat"
        description="Chat used in comprehensive tools where conversation is the primary focus."
        href={`https://design.visa.com/patterns/chat/full-page-chat`} 
        thumbnail={`https://design.visa.com/assets/patterns/chat/full-page-chat.svg`}
        hasChevron
        hoverColor={colorGreen}
    />

    <LibraryCardLarge 
        title="Dialog chat" 
        description="Chat that opens in a smaller window that overlays the main content of the page."
        href={`https://design.visa.com/patterns/chat/dialog-chat`} 
        thumbnail={`https://design.visa.com/assets/patterns/chat/modal-chat.svg`}
        hasChevron
        hoverColor={colorGreen}
    />
    <LibraryCardLarge 
        title="Panel chat" 
        description="Chat that appears beside the main content, enabling users to interact with the rest of the interface simultaneously."
        href={`https://design.visa.com/patterns/chat/panel-chat`} 
        thumbnail={`https://design.visa.com/assets/patterns/chat/panel-chat.svg`}
        hasChevron
        hoverColor={colorGreen}
    />
</LibraryCardListLarge>


---

# usage

---
title: Chat
tab_title: Usage
description: Interfaces that enable users to conduct conversations with human and AI assistants.
meta_description: Learn how to design chat interfaces that enable users to conduct conversations with human and AI assistants.
thumbnail: assets/patterns/chat-graphic.svg
tab_order: 1
keywords: ["AI assistant", "chatbot", "dialogue design", "conversation interface"]
related: 
  components: 
    - button
    - horizontal-navigation
    - progress
    - vertical-navigation
---

Chat patterns provide a framework for designing chat interfaces. This includes person-to-person chats, as well as interactions with AI assistants or chatbots. They typically include components such as input fields, avatars, icons, message bubbles, and more.<br/><br/>
Also known as: AI assistant, chatbot, dialogue design, conversation interface.

## Anatomy

<img src="https://design.visa.com/assets/patterns/chat/chat-anatomy.svg" alt="A chat interface with callout A indicating the required navigation, callout B indicating the required message bubble, callout C indicating the optional avatar, callout D indicating the optional message actions, callout E indicating the required message area, and callout F indicating the required input field"/> 
**A. Navigation (required):** Vertical navigation or top app bar containing actions and navigation items.<br/>
**B. Message bubble (required):** Area containing chat participants’ sent or received messages.<br/>
**C. Avatar (optional):** Icon, initials, or image avatar representing chat participants.<br/>
**D. Message actions (optional):** Icon buttons enabling users to perform actions like flagging responses or copying content.<br/>
**E. Message area (required):** Area containing sent and received messages between chat participants.<br/>
**F. Input field (required):** Text area containing icon buttons enabling users to enter text or perform actions.

## Usage

  When to use and when not to use different types of chat patterns

- Pattern: For more complex chat scenarios like long-form content generation, code creation, or to provide access to chat histories.<br/><br/>To enable users to focus on the chat interface without distractions.
- When to use: To provide access to other elements in the interface during the chat experience. Use a panel or dialog instead.

- Pattern: To provide access to other elements in the interface during the chat experience.
- When to use: If users are unlikely to multi-task between the chat and the rest of the interface.<br/><br/>If users would benefit from only focusing on the chat.

- Pattern: To provide easy access to support across the site or application.<br/><br/>To provide access to other elements in the interface during the chat experience.<br/><br/>If users don’t need access to chat histories.
- When to use: For more complex chat scenarios like long-form content generation, code creation, or to provide access to chat histories.<br/><br/>If users would benefit from only focusing on the chat.

## Best practices
- Ensure chat interfaces are easy to use with clear options for sending messages, sharing content, or ending the conversation. 
- Always be transparent about how user data is handled and ensure sensitive conversations are protected.
- Ensure sent and received messages appear visually different so users can differentiate between them. 
- Ensure AI chatbots can handle a wide range of inputs including typos or different wording. 
- Ensure AI chatbots are regularly updated based on user interactions and feedback. 
- Ensure users can easily get help or escalate issues, especially when interacting with AI. 
- Provide appropriate feedback about the status of messages, such as sent, delivered, or read.

### Representing chat participants

Accurately representing chat participants helps users identify whether they’re communicating with a human or AI. Components such as message bubbles, avatars, display names, and icons help distinguish participants and provide essential context during a conversation. 
- Use clear icons to help users identify whether they’re communicating with human or AI participants. 
- Use the message bubble placement to differentiate between sent and received messages. For left-to-right languages, align the sender's messages to the right and recipient’s messages to the left. Reverse this alignment for right-to-left languages. 
- Incorporate the user’s avatar or display name to personalize the experience and provide visual cues.
- Maintain consistent styling and placement for these components across the experience to avoid confusion.

### Prompt suggestions
Prompt suggestions help users understand the purpose of a chat interface and encourage them to initiate conversation in a way that’s easy to understand and respond to. While they can be used in any chat setting, they are especially useful in interactions with chatbots or generative AI, as they guide users to provide information in a format that the AI can understand and respond to effectively. For more on placement, visit the [Layouts](https://design.visa.com/patterns/chat/usage#layouts) section below. 
- Provide prompts that are simple, clear, and easy to understand.
- Include prompts if they’re helpful and relevant to the context of the chat.
- Ensure users can always bypass or ignore the prompt suggestions.

### Response feedback

Enabling users to provide feedback gives valuable insight on how well the chat interactions are being received. This is especially important for chatbots and generative AI and can be achieved through actions such as like/dislike icons or flags.

<img src="https://design.visa.com/assets/patterns/chat/chat-feedback.svg" alt="A feedback survey is initiated and completed in the chat by the user"/>
- Always allows users to report any inaccuracies, inappropriate content, or areas of improvement for AI outputs.
- Keep the process of receiving feedback straightforward and quick, not requiring users to navigate away from the chat.
- Consider providing an option for users to leave more detailed feedback along with flagging or voting.

### Time stamps
Time stamps indicate when messages were sent and received. Timestamps should always be included for human-to-human chats to help manage expectations, but are not necessary for generative AI. To provide additional context, consider the following:
- Indicating the exact length since a message was sent for new messages, such as "15 minutes ago" or "Just now". 
- Display the time without the date for messages sent earlier in the same day but more than an hour ago, such as "10:30 AM".
- Use "Yesterday" along with the time for messages sent between 24 and 48 hours ago, such as "Yesterday, 10:30 AM".
- Display the date and time for messages sent more than two days ago, such as "10/05/2021, 10:30 AM".

<img src="https://design.visa.com/assets/patterns/chat/chat-timestamps.svg" alt="A chat window with timestamps for received 'Yesterday, 12:34PM' and sent 'Just now' messages"/>
- Position time stamps in a consistent location, usually next the user’s name or avatar.
- Ensure time stamps clearly indicate when messages were sent to help users follow the conversation.
- Consider the user's location and time zone. Follow date and time format guidelines found in [Grammar and punctuation](https://design.visa.com/content/grammar). 

### Chat history

Chat histories allow users to keep track of and continue past and present conversations, enabling them to revisit previous queries and responses. They are commonly used in generative AI and support chats, although their functionalities might vary in each context.<br/><br/>

**Note:** Always ensure the handling of chat histories is in compliance with relevant data protection and privacy regulations.

<img src="https://design.visa.com/assets/patterns/chat/chat-history.svg" alt="A chat log window that contains 'search field, 'pinned chats', '1 week ago', and 'last 30 days'."/>

- Ensure chat histories are easily accessible. Learn more about the placement of chat history in [Layouts](https://design.visa.com/patterns/chat/usage#layouts) below.
- Ensure chat histories include all past interactions, queries, responses, and timestamps for the duration they are stored.
- Be transparent about how long chat histories are stored and how they are used.
- Allow users to search their chat history. This can be particularly helpful in long or complex interactions.

### Action menu

Action menus allow users to perform various operations related to their conversation. Users can rename a conversation, search within it, download the transcript, or even delete the chat. In human-to-human chats, options like muting a conversation or adding participants are common. In chats with chatbots or generative AI, users might find options to start a new conversation, rename it, or download the chat helpful.
- Consider including an option to rename the conversation. This helps users distinguish between different chats.
- Provide a search functionality within the chat. This can help users find specific information from past messages quickly.
- Allow users to download the chat. This can be useful for users who wish to save or archive their conversations.

### Pinning a chat
Pinning a chat enables users to save important interactions for future reference. This is particularly helpful in advanced chat tools, where it enhances user accessibility and organization. The most common method is using a pin icon. In the context of human-to-human chats, pinning can be used to prioritize ongoing conversations or to keep track of important discussions. In interactions with chatbots or generative AI, pinning could be used to highlight useful bot responses or to earmark complex interactions for further review.<br/><br/>

**Note:** This isn’t recommended for mobile applications as it can be difficult to implement with space constraints.

<img src="https://design.visa.com/assets/patterns/chat/pinning-chat.svg" alt="A chat log window with pin icon and message in the 'pinned chats' category"/>
- Always ensure the pinning process is simple and intuitive.
- Use clear visual indicators such as icons and states to show which chats or messages have been pinned.

### File upload
File uploads help users share information, enhancing the depth and versatility of conversations. In human-to-human interactions, file uploads enable users to exchange data beyond text. In human-to-AI chats, users can provide additional data to the AI, such as documents for analysis or images for processing. File uploads can be implemented in many ways based on use case and technical capabilities. For more, reference [File upload](https://design.visa.com/patterns/file-upload/usage).

<img src="https://design.visa.com/assets/patterns/chat/chat-file-upload.svg" alt="Two chat windows display uploaded files in pending and sent messages, each with file type icons, names, sizes, and remove buttons."/>

### Progress 
Progress indicators help manage user expectations during interactions with generative AI. Indeterminate progress indicators are used when a process cannot be precisely calculated. They’re used to inform users about ongoing processes in the background and help maintain user engagement by signaling that the chatbot is actively working on a task.

<img src="https://design.visa.com/assets/patterns/chat/progress.svg" alt="A chat window displays a spinning progress indicator while the generative AI assistant generates its response."/>

- Follow all best practices and guidelines for indeterminate progress indicators in [Progress](https://design.visa.com/components/progress/usage).
- Ensure the progress indicators are easily noticeable but not disruptive to the chat experience.
- Offer an estimated completion time or a cancel option when processing times are expected to be long.

#### Typing indicators

Typing indicators provide a real-time indication that the other party is actively writing a message. They enhance the communication experience in both human-to-human and human-to-chatbot interactions, reducing frustration and facilitating more immediate and interactive exchanges. There are generally two ways to indicate real-time typing: text or graphic. 
- Use real-time typing indicators to enrich the conversational flow, making it feel more natural and engaging.
- Consider simulating real-time typing for chatbots to mimic a more human-like conversation.
<br/>

    
        ##### Text-based typing indicators
        Text-based typing indicators, like "username is typing...", personalize the chat experience by clearly showing who’s actively responding in real-time.
        <img src="https://design.visa.com/assets/patterns/chat/text-indicator.svg" alt="A chat window with typing indicator reads 'Stacy Taylor is typing…"/>
        - Use in group chats to help clarify who’s typing.
        - Use to reduce visual elements in the interface.
    
    
        ##### Graphic-based typing indicators

        Graphic-based typing indicators, such as an animated ellipsis, provide a visually simple and space-efficient way to signal real-time typing activity.
        <img src="https://design.visa.com/assets/patterns/chat/graphic-indicator.svg" alt="A chat window with graphic-based typing indicator displays three dots"/>
        - Use in one-on-one chats when it’s clear who’s typing.
        - Ensure the animation simple and universally understood.
    

### Displaying errors

Error messages help indicate when something’s gone wrong and inform users how to proceed. They can appear for individual messages or chat conversations as a whole, depending on the error.

<img src="https://design.visa.com/assets/patterns/chat/error-display.svg" alt="A chat window displays a 'Connection issue. Try again.' error with an icon above the messages and a 'Error, message failed to send.' alert with an icon below."/>

- Follow all best practices and guidelines found in [Messaging](https://design.visa.com/content/messaging).
- Always provide options for users to re-send a message that failed.

## Layouts
The chat pattern has multiple layouts to accommodate different visual designs and user needs. 

### Full-page 
Full-page chats are often used for comprehensive chat tools where conversation is the primary focus, as the larger interface provides space for additional features like managing chat history, accessing saved chats, and initiating new conversations. These are most commonly used for generative AI. In this layout, chat history is usually included using vertical navigation.

<img src="https://design.visa.com/assets/patterns/chat/full-page-layout.svg" alt="A full-page chat interface combines a vertical navigation for chat history and saved chats with an active conversation window."/>

- Position the "New chat" button in a consistent place on every page of your interface.
- Use vertical navigation to provide easy access to chat history and saved chats. 
- Include a landing page with an introduction to the tool and prompt recommendations for first-time users. 
- Consider allowing users to change language models or source libraries within a settings menu when possible.

### Panel
The panel layout is best for multitasking environments, as the chat panel can remain open while users interact with the main content on the page. It's commonly placed to the side of the main content, providing easy access for ongoing discussions without distracting from additional content on the screen.

<img src="https://design.visa.com/assets/patterns/chat/panel-layout.svg" alt="A chat opened as a panel in the right side of the page."/>

- Position the panel on the side of the main content for multitasking.
- Include an option to close the panel when user interaction is not required.
- Allow users to minimize the panel without ending the chat.

### Dialog
The dialog layout opens the chat in a smaller window that overlays the main content of the page. This layout is best for brief, targeted chats, providing a non-intrusive way to provide real-time support without disrupting the user's primary navigation.

<img src="https://design.visa.com/assets/patterns/chat/dialog-layout.svg" alt="A small chat dialog opened in the bottom right of the page."/>

- Position the dialog window consistently, typically to the right of the screen, to avoid covering the main content.
- Display the chat history within the dialog, with the latest messages near the bottom.
- Provide a clear option to close the dialog, typically an "X" or "Close" button in the upper right corner, to allow users to return to the main content whenever they wish.
- Allow users to minimize dialog without ending the chat.

## Platform considerations
Chat is available for both web and mobile platforms. Learn about screen size considerations below.

### Mobile
The mobile chat variant may be used to accommodate small screens.

<img src="https://design.visa.com/assets/patterns/chat/chat-platform-mobile.svg" alt="A mobile chat variant is opened in full screen"/>

- Ensure mobile chats always open in a full screen.
- Ensure users can exit the chat at any point by including the appropriate icons, like back or close.

## Content
- Use clear and concise language. Avoid jargon, complex sentences, or ambiguous phrases that might confuse users.
- Use sentence case, except for proper nouns or acronyms.
- Follow guidance in [Horizontal navigation](https://design.visa.com/components/horizontal-navigation/usage) and [Vertical navigation](https://design.visa.com/components/vertical-navigation/usage) when writing navigation labels. 
- Reference [Button](https://design.visa.com/components/button/usage) for guidance on creating effective button labels.  
- Visit [Messaging](https://design.visa.com/content/messaging) for specific guidance on how to craft content for success, warning, and error messaging.

### Voice and tone

Voice and tone are key elements that establish how products sound and feel. Voice refers to Visa’s personality and values, which should appear consistently across experiences, while tone is an expression of mood and changes depending on the context. Learn how to create products that sound and feel like Visa by learning the foundational pillars of our [Voice and tone](https://design.visa.com/content/voice-and-tone).
- Maintain a consistent voice that aligns with Visa product experiences throughout the chat experience.
- Adjust the tone for the context. For example, use an instructional and helpful tone for error messages.


---

# accessibility

---
title: Dynamic table
description: Dynamic grid enabling data interaction, manipulation, and criteria-based analysis.
meta_description: Dynamic grid enabling data interaction, manipulation, and criteria-based analysis.
thumbnail: assets/patterns/dynamic-table-graphic.svg
tab_order: 2
---

## Best practices

Follow general best practice guidance to create accessible experiences for users of all abilities.
- Ensure focus is not lost when table data is updated dynamically, such as during sorting, filtering, or pagination actions.
- If a table has no interactive elements, ensure that screen readers can still navigate the table structure effectively. This may involve using tabIndex to put focus on the table element itself.

### Table structure
- Follow [Table](https://design.visa.com/components/table) accessibility guidelines for multi-select implementations.
- Use proper table markup with `<table>`, `<thead>`, `<tbody>`, `<th>`, and `<td>` elements to ensure screen readers can correctly interpret the table structure.
- Apply `scope='col'` to all column headers (`<th>`) to explicitly associate them with their respective columns.
- Apply `scope='row'` to the cell within each row that best serves as a name or identifier for the entire row. This is typically the first column in the row and helps screen reader users understand the row's context.

### ARIA labels and descriptions
- When using `aria-label` on cells, avoid including role names such as "row", "table", "column", or "cell" in the label text. Screen readers will already announce the element's role, so including it again creates redundant information.
- Ensure any row-wide `aria-label` attributes or `aria-labelledby` references point to the cell with `scope='row'` (the row header) to provide consistent context across the row.
- Use `aria-describedby` to associate additional descriptive information with cells when needed, such as error messages or supplementary details.

### Sorting
- Add `aria-sort` to column headers that are actively sorted, using the appropriate value: `ascending` or `descending`. This helps screen reader users understand the current sort order.
- Ensure sort buttons have clear `aria-label` attributes that describe both the column name and the action, such as "Sort by Status, ascending" or "Sort by Date, descending".
- Provide visual and programmatic feedback when sort order changes to keep all users informed of the current state.

### Selectable rows
- Follow [Checkbox](https://design.visa.com/components/checkbox) accessibility guidelines for multi-select implementations.

### Expandable rows
- Follow [Accordion](https://design.visa.com/components/accordion) accessibility guidelines for expandable row implementations.

### Pagination
- Follow [Pagination](https://design.visa.com/components/pagination) accessibility guidelines to ensure users can navigate between pages efficiently.

### Loading states
- Use `role='status'` or `aria-live='polite'` for loading indicators to announce when data is being fetched without interrupting the user's current task.
- Use `aria-busy='true'` on the table element while data is loading to inform assistive technologies that the content is being updated.

---

# index

---
title: Dynamic table
description: Dynamic grid enabling data interaction, manipulation, and criteria-based analysis.
meta_description: Dynamic grid enabling data interaction, manipulation, and criteria-based analysis.
page_size: full-width
thumbnail: assets/patterns/dynamic-table/dynamic-table-graphic.svg
tab_title: Code
show_table_of_contents: false
examples:
  - slug: "default"
    title: "Default dynamic tables"
  - slug: "loading-states"
    title: "Dynamic table loading states"
  - slug: "multi-select"
    title: "Multi-select dynamic tables"
  - slug: "expandable"
    title: "Expandable dynamic tables"
  - slug: "layouts"
    title: "Dynamic table layouts"
  - slug: "filters"
    title: "Dynamic table with filters"
---

<LibraryCardListLarge>
    <LibraryCardLarge 
        title="Default dynamic tables" 
        description="Tables that enable users to interact with one column at a time."
        href={`https://design.visa.com/patterns/dynamic-table/default`} 
        thumbnail={`https://design.visa.com/assets/patterns/dynamic-table/default-dynamic-table.svg`}
        hasChevron
        hoverColor={colorGreen}
    />
    <LibraryCardLarge 
        title="Dynamic table loading states" 
        description="Tables that visually indicate loading or processing states of a task or function."
        href={`https://design.visa.com/patterns/dynamic-table/loading-states`} 
        thumbnail={`https://design.visa.com/assets/patterns/dynamic-table/dynamic-table-loading-states.svg`}
        hasChevron
        hoverColor={colorGreen}
    />
    <LibraryCardLarge 
        title="Multi-select dynamic tables" 
        description="Tables that enable users to select and interact with multiple rows simultaneously."
        href={`https://design.visa.com/patterns/dynamic-table/multi-select`} 
        thumbnail={`https://design.visa.com/assets/patterns/dynamic-table/multi-select-dynamic-tables.svg  `}
        hasChevron
        hoverColor={colorGreen}
    />
    <LibraryCardLarge 
        title="Expandable dynamic tables" 
        description="Tables that enable users to expand individual rows to reveal additional information."
        href={`https://design.visa.com/patterns/dynamic-table/expandable`} 
        thumbnail={`https://design.visa.com/assets/patterns/dynamic-table/expandable-dynamic-tables.svg`}
        hasChevron
        hoverColor={colorGreen}
    />
    <LibraryCardLarge 
        title="Dynamic table layouts" 
        description="Tables that support action bars and pagination."
        href={`https://design.visa.com/patterns/dynamic-table/layouts`} 
        thumbnail={`https://design.visa.com/assets/patterns/dynamic-table/dynamic-table-layouts.svg`}
        hasChevron
        hoverColor={colorGreen}
    />
    <LibraryCardLarge 
        title="Dynamic table with filters" 
        description="Tables that enable users to refine results by applying specific criteria."
        href={`https://design.visa.com/patterns/dynamic-table/filters`} 
        thumbnail={`https://design.visa.com/assets/patterns/dynamic-table/dynamic-table-with-filters.svg`}
        hasChevron
        hoverColor={colorGreen}
    />
</LibraryCardListLarge>


---

# usage

---
title: Dynamic table
tab_title: Usage
tab_order: 1
description: Dynamic grid enabling data interaction, manipulation, and criteria-based analysis.
meta_description: Learn how to implement dynamic grids to enable data interaction, manipulation, and criteria-based analysis.
thumbnail: assets/patterns/dynamic-table-graphic.svg
keywords: ["data grids", "interactive table", "editable table", "live table", "clickable table", "responsive table", "UITableView (iOS)", "ListView (Android)"]
related:
  components:
    - table
    - pagination
    - progress
---

Dynamic tables combine a static [Table](https://design.visa.com/components/table) with various other components to enable users to interact with one or more rows of data.<br/><br/>

Also known as: data grids, interactive table, editable table, live table, clickable table, responsive table, UITableView (iOS), ListView (Android).

## Anatomy

<img src="https://design.visa.com/assets/patterns/dynamic-table/dynamic-table-anatomy.svg" alt="A dynamic table with callout A indicating the optional action bar, callout B indicating the required table, callout C indicating the optional sorting icon, callout D indicating the optional row actions button, and callout E indicating the optional pagination."/>

**A. Action bar (optional):** Area containing actions related to the entire table or selected rows within the table. <br/>
**B. Table (required):** Table component consisting of rows and columns. <br/>
**C. Column actions button (required):**  UI icon button that launches an actions menu for the associated column. Can also be displayed as a sorting button when additional actions aren’t needed. <br/>
**D. Row actions button (optional):**  UI icon button that launches an actions menu for the associated row. <br/>
**E. Pagination (optional):**  A set of links that allow users to navigate a large collection of data split into multiple pages. <br/>

## Usage

When to use and when not to use different types of dynamic tables

- Component: For basic interactivity such as sorting, filtering, and pagination.
- When to use: If complex interactivity is needed for individual or multiple rows.

- Component: Multi-select
- When to use: If users need to select one or more table rows to perform actions.
- When not to use: If users don’t need to select rows for further actions.

- Component: Expandable
- When to use: If there is supplementary information or data that does not need to be immediately displayed to the user.<br/><br/>If supplementary data requires extra query time.
- When not to use: If there is important information that should be displayed to the user immediately.

## Best practices
- Limit visual elements that don’t add meaning or interactivity to the data displayed in the table. 
- Ensure the default view uses a logical sorting method, such as most to least relevant to the user.
- Consider using pagination if the user needs to scroll to see the entire table. 
- Include clear error messaging if data can’t be loaded or if it’s taking longer than expected.

## Layouts
The dynamic table pattern has multiple layouts to accommodate different visual designs and user needs.

### Default
The default layout is ideal for providing basic interactivity like sorting, filtering, and pagination. It enables users to take actions on one row at a time, but doesn’t enable bulk actions.

<img src="https://design.visa.com/assets/patterns/dynamic-table/dynamic-table-layout-default.svg" alt="Dynamic table showing an action bar containing a header row with column sorting, a column options icon, 5 rows, and pagination at the bottom"/>

- Include inline actions or a [Row actions](https://design.visa.com/patterns/dynamic-table/usage#row-actions) button within each row to enable users to perform actions. 
- Consider adding an [Action bar](https://design.visa.com/patterns/dynamic-table/usage#action-bar) for actions that apply to the whole table, such as filtering.

### Multi-select
The selectable rows layout enables users to interact with multiple rows at once. This is helpful for tables requiring complicated or bulk actions.<br/><br/>
This functionality is generally indicated by a checkbox in the first column. Users can select a row by selecting its associated checkbox. Selecting the checkbox in the column header automatically selects every row. 

<img src="https://design.visa.com/assets/patterns/dynamic-table/dynamic-table-selectable-rows.svg" alt="Dynamic table showing an action bar containing buttons and filters, a header row with column sorting, a column options icon, 5 rows with 3 selected, and pagination at the bottom"/>

- Include an [Action bar](https://design.visa.com/patterns/dynamic-table/usage#action-bar) to allow users to perform actions on the selected rows.
- Consider including [Row actions](https://design.visa.com/patterns/dynamic-table/usage#row-actions) button for actions that can only be applied to one row at a time. 
- Use clear visual styling to indicate selected rows, such as a selected icon or a change in background color.
- Consider displaying the number of columns selected to inform users how many selections they’ve made.

### Expandable 
The expandable rows layout uses accordions that don’t display all the available data until manually expanded by the user. This is helpful when there’s a significant amount of data that can’t be shown at once, or to provide notes or additional data that isn’t represented by a table column. 

<img src="https://design.visa.com/assets/patterns/dynamic-table/dynamic-table-expandable-rows.svg" alt="Dynamic table showing a header row with column sorting, and 3 rows with the first one expanded."/>

- Use a chevron UI icon button to clearly indicate when there’s more data available. 
- Use clear placement so users can identify if expanded content pertains to specific column headings. 
- Maintain the expanded or collapsed state of rows if the user leaves and returns to the page.
- Ensure expanded information loads quickly to prevent user frustration. If there’s a delay, use a [Progress](https://design.visa.com/components/progress) indicator.
- Ensure the behavior of expanded rows is consistent across other data tables in the same application.
- Ensure screen readers announce whether a row is expanded or collapsed. For more information, reference [Accordion](https://design.visa.com/components/accordion). 
- Avoid complex interactions within expanded content to ensure all users can fully access and interact with important data.

## Behaviors
Dynamic tables have various behaviors designed to make data easy to understand and interact with. Reference the section below to learn about optional features that can be implemented based on the use case. 

### Filtering
Filters refine results by including or excluding items based on specific criteria, so only the most relevant information is presented. Reference the [Filters](https://design.visa.com/patterns/filters) pattern for additional layouts and more details.

#### In-table filters

In-table filters are specifically used in dynamic tables and enable users to refine the table data directly from a menu in the column header. Users can open a dialog by selecting the options button within the header. Selecting “Apply” closes the dialog and applies the chosen filters. Only one table column can be filtered at a time.

<img src="https://design.visa.com/assets/patterns/dynamic-table/dynamic-table-filter.svg" alt="Dynamic table showing a header row with column sorting, column action buttons, and an open column action menu with two filters selected, and 8 table rows."/>

#### Filter dialog

In this layout, filters are displayed in a temporary dialog activated by a filter button, typically located in an action bar. The dialog closes when the user selects “Apply” or dismisses it by interacting outside the dialog. Selecting outside the dialog without selecting “Apply” will discard any changes. 

<img src="https://design.visa.com/assets/patterns/dynamic-table/dynamic-table-filter-1.svg" alt="Dynamic table showing a header row with buttons and 2 applied filters in a dropdown menu, column sortings, and 5 rows."/>

### Sorting
Sorting helps users find the information they need by organizing data into a preferred order. It can help identify trends, patterns, or anomalies within a dataset. Unlike filtering, sorting only reorders existing data—it doesn’t hide or remove items. Common ways to sort data include alphabetically, numerically, and chronologically.<br/><br/>

In the example below, the rows are sorted from most to least critical based on the "Status" column.

<img src="https://design.visa.com/assets/patterns/dynamic-table/dynamic-table-sort.svg" alt="Dynamic table showing a status column sorted descending from most critical to least."/>

- Enable users to sort a column by selecting the icon button.
- Ensure the column order reverses if users select a header or arrow a second time.
- Use the sortable or sortable-alt icon to indicate a column can be sorted. 
- Use an up-facing arrow to indicate the column is in ascending order. 
- Use a down-facing arrow to indicate the column is in descending order.

#### Ascending and descending order

Use the following table to identify the ascending or descending order for common data types.

Ascending and descending order for types of data

- Data type: Lowest to highest value
- Ascending: Highest to lowest value

- Data type: Earliest date to most recent date
- Ascending: Most recent date to earliest date

- Data type: Least critical to most critical item
- Ascending: Most critical to least critical item

- Data type: A-Z
- Ascending: Z-A

- Data type: ‘True’ appears at the top
- Ascending: ‘False’ appears at the top

### Column actions
When columns require more actions than sorting, use a dropdown column actions button. Common actions include sorting, pinning, hiding, and filtering columns.

<img src="https://design.visa.com/assets/patterns/dynamic-table/dynamic-table-column-actions.svg" alt="Dynamic table with column action buttons for each column and 6 rows."/>

- Use a commonly recognized icon such as three dots or a gear to signify there are more actions.
- Only include multiple column actions in complex dynamic tables that require advanced features.

#### Managing which columns are shown

For large tables with many columns, consider enabling users to decide which ones are displayed in the table. This can be achieved by including a dropdown menu in an [action bar](https://design.visa.com/patterns/dynamic-table/usage#action-bar). It’s also common to include “Hide column” as an option in the column actions menu.

- Show all columns by default to ensure users are aware of all the data included in the table. 
- Ensure users can hide a column from view by deselecting it from the menu. 
- Ensure that users cannot hide columns that are essential to the function of the table, such as actions.
- Consider displaying the number of columns hidden to clearly indicate the current state of the table. 

<img src="https://design.visa.com/assets/patterns/dynamic-table/dynamic-table-column-actions-1.svg" alt="Dynamic table with a header row with buttons for exporting, column actions, and filters."/>

### Pagination
The pagination component is a set of links enabling users to navigate tables divided across multiple pages. This helps reduce cognitive load by reducing the amount of data shown at once. For general information on the pagination component, reference [Pagination](https://design.visa.com/components/pagination).

<img src="https://design.visa.com/assets/patterns/dynamic-table/dynamic-table-pagination.svg" alt="Dynamic table with 4 rows and pagination."/>

- Use pagination when the data can’t be easily viewed on one page or requires significant scrolling. 
- Place the pagination component below the last row of the dynamic table. 
- Use the default pagination component for complex tables when space permits.
- Use the slim pagination component for less complex table with fewer pages, or when space is limited.

### Row actions
Row actions enable users to edit, delete, or perform other actions on an individual row. They’re typically used in complex tables when there are multiple actions the user can take.<br/><br/>
Row actions can be included using inline icon buttons, or with a dropdown menu. Inline icon buttons work well if there are one or two actions, while a dropdown menu can be used to provide more than two.

<img src="https://design.visa.com/assets/patterns/dynamic-table/dynamic-table-row-actions.svg" alt="Dynamic table with column sorting buttons for each column and 6 rows with action buttons for each row."/>

- Use icon buttons rather than text buttons within rows to avoid information overload.
- Make sure the actions are relevant and allowed. For example, don’t allow users to download sensitive or private data.

### Action bar
The action bar contains actions that apply to the whole table or multiple selected rows in the table. It’s typically placed above the table to ensure it’s visible and accessible to users.

<img src="https://design.visa.com/assets/patterns/dynamic-table/dynamic-table-action-bar.svg" alt="Dynamic table showing an action bar containing buttons and filters, a header row with column sorting, and 3 rows"/>

- Follow [Button guidelines](https://design.visa.com/components/button) to implement primary, secondary, and tertiary buttons to visually differentiate actions. 
- Include a clear button or selection chip to enable users to deselect all selected rows at once. 
- Consider disabling actions that can’t be performed on the whole table until rows are selected to avoid frustration.

### Notifications
Dynamic tables can also include a notification column to indicate new or unread notifications. This helps provide users with critical updates and alerts within the context of their data.

<img src="https://design.visa.com/assets/patterns/dynamic-table/dynamic-table-notifications.svg" alt="Dynamic table showing an action bar containing buttons and filters, a header row with column sorting, and 3 rows with a column with new or unread indicators"/>

- Use a [Badge](https://design.visa.com/components/badge) component to indicate unread notifications. 
- Consider placing new or unread notifications at the top of the table to ensure they’re seen or announced first. 
- Consider including “Notification status” as a sort or filter criteria so users can access unread notifications quickly. 
- Provide a clear method for clearing notifications, such as a row action or "Mark all as read" button in the action bar.

### Scroll
Scroll bars enable users to navigate tables with many rows that aren’t all visible at once. This is particularly helpful when interfaces have limited space to ensure users can still access the data.<br/><br/>
Scrolling can be implemented to allow vertical scrolling, horizontal scrolling, or both. Vertical scrolling is helpful when there’s limited vertical space, while horizontal scrolling is helpful when there’s limited horizontal space. Learn about both scrolling methods below.

- Ensure the scroll bar is visible to help indicate the user’s location in the table and how much more content is available. 
- Ensure column headers and corresponding rows are directly aligned to avoid confusion.

#### Vertical scroll with sticky header

Vertical scroll can help users access data when there’s limited vertical space and all rows aren’t visible at once. This is the default scrolling behavior for most tables and is generally more intuitive for users. This helps when there are few columns but many rows, tables are likely to be viewed on mobile devices, or you want to maintain the visibility of all columns.<br/><br/>
When implementing vertical scroll, it’s recommended to use a sticky header. Sticky headers remain fixed at the top of the table even when the user scrolls, ensuring they can easily identify what column a cell pertains to.

<img src="https://design.visa.com/assets/patterns/dynamic-table/dynamic-table-sticky-header.svg" alt="Dynamic table showing a sticky header and vertical scrollbar"/>

- Use a [Divider](https://design.visa.com/components/divider) or other visual indicator to ensure the sticky header appears visually different from other rows.
- Use elevation to visually indicate that the sticky header is floating “above” the rest of the table’s data.
- Ensure the scroll bar is displayed by default so users are aware there's more data available.

#### Horizontal scroll

Horizontal scroll can help users access data when there’s limited horizontal space and all columns aren’t visible at once. This helps when there are many columns and users need to be able to see all the data.<br/><br/>
It’s recommended to enable users to pin a column when implementing horizontal scrolling. This enables users to keep a single column in view for easier comparison.

<img src="https://design.visa.com/assets/patterns/dynamic-table/dynamic-table-horizontal-scroll.svg" alt="Dynamic table showing a pinned column and horizontal scrollbar"/>

- Use elevation to visually indicate that the sticky header is floating “above” the rest of the table’s data.
- Ensure the scroll bar is displayed by default so users are aware there's more data available.

#### Vertical and horizontal scroll

In certain cases, especially with large data sets, vertical and horizontal scrolling can be combined to provide access to all the data cells. Use this method sparingly, as it creates a complicated interaction and can be difficult to navigate on mobile devices. 

<img src="https://design.visa.com/assets/patterns/dynamic-table/dynamic-table-vert-horiz-scroll.svg" alt="Dynamic table showing a vertical and horizontal scrollbar"/>

- Consider alternate ways to present data such as pagination, filters, or expandable rows whenever possible. 
- Ensure the scroll bars are displayed by default so users are aware there's more data available.

### Progress indicators
Progress indicators help users identify when data hasn’t finished loading. This is especially helpful for complex data tables, which can have lengthy load times. For general guidelines on progress indicators, reference [Progress](https://design.visa.com/components/progress).

<img src="https://design.visa.com/assets/patterns/dynamic-table/dynamic-table-indeterminate-progress-3.svg" alt="Dynamic table showing an indeterminate progress bar"/>

- Use a linear progress indicator in most cases to save space and align with the table layout. 
- Place the indicator at the top of the table, stretching the entire width.
- Skeleton loading can be used as additional visual indication that the data in the table is loading.
- Ensure the progress indicator uses different visual styling from the table header.

## Content
- Use sentence case for all content except proper nouns, names, or abbreviations.
- Use straightforward language without jargon.
- Limit use of abbreviations unless the abbreviation is commonly understood and improves readability due to space constraints or line length. 
- Ensure column and row headers have distinct labels. If duplicates are required, add additional context to ensure screenreaders can differentiate them. 

### Table titles and subtitles

- Use informative titles that describe the table as a whole.
- Use subtitles to describe complex tables. 
- Don’t include punctuation for table titles.
- Limit titles to three to five descriptive words. If your title can’t be condensed, consider using a subtitle with your title. 
- Limit subtitles to one to two short sentences with punctuation. 

### Column headers

- Clearly label columns using short, concise, and scannable column headers. 
- Ensure column headers accurately describe the contents so users can interpret the data without additional context. 
- Include symbols for units or measurement along with its name. For example "Temperature (°F)"

### Table content

- Use short, scannable content within table rows. 
- Don’t include symbols, such as “$”. Only include those within the header to avoid issues filtering information.
- Only use punctuation when using decimals. Ensure all decimal places are consistent for filtering information.

## Platform considerations

### Recommended for responsive web only

When dynamic tables are complex and dense, they are best suited for responsive web sites and applications. Use caution implementing dynamic table on screen sizes smaller than 768px.


---

# index

---
title: Feedback and status
tab_title: Usage
description: Learn which components to use when communicating contextual or system feedback and status.
meta_description: Learn which components to use when communicating contextual or system feedback and status.
thumbnail: assets/patterns/feedback-and-status/feedback-and-status.svg
keywords: ["System messaging", "status alert", "global status message", "informational notice", "site notice", "page notification", "validation bar"]
related: 
  baseElements:
    - color
  content:
    - messaging
---

Feedback and status let users know what’s happening, understand the results of actions, discover what they can do next, and avoid mistakes. Both provide information to users that may (or may not) require action and are used across a range of components that can be broadly categorized as alerts or status updates. This guidance outlines the differences between feedback and status, and the components used to communicate both. It covers everything from how to decide on the right component for your context, where to place it, and its level of disruption. <br/><br/>
For specific guidance on how to craft content for feedback and status components including information, success, warning, and error messaging, visit [Messaging](https://design.visa.com/content/messaging). <br/><br/>
Also known as: System messaging, status alert, global status message, informational notice, site notice, page notification, validation bar.

## Best practices
- Use sparingly, especially when interrupting tasks. 
- Only offer essential information to the system or workflow. 
- Limit the use for common actions, but always use to confirm destructive actions that users can’t undo.
- Provide the appropriate visual cues and responses to help users quickly assess and identify the alert and respond.
- Only display one feedback or status alert at a time. Alerts should not be stacked one after another. 
- Include actions as needed. In most cases, alerts would be dismissed by other user interaction elsewhere.
- Reference individual component guidelines to learn about best practices for different screen sizes.

## Feedback component examples
Feedback typically occurs when a user takes action, interacts with a system or with an item in a system. The effects of that action are then communicated back to the user in the form of messaging that guides their next action—creating a feedback loop. Below are some examples of the components commonly used to create a feedback alert. 

### Dialog
Dialogs are a modal interface that gives feedback on an action that was just taken that requires additional action before the user can move forward.
<img src="https://design.visa.com/assets/patterns/feedback-and-status/feedback-dialog.svg" alt="A dialog informs users they have unsaved changes with a 'Save and quit' button."/>
**Usage:** Since the main mechanism is disruption to the user’s workflow, limit use to critical moments, confirmations of destructive actions, or tasks that require action.<br/><br/>
**Placement:** Appears in the middle of the user’s main workflow.<br/><br/>
**Persistence:** Should persist, keeping the user’s focus and blocking their access to the parent window until the required action is taken or window is dismissed. <br/><br/>
[Explore dialog guidelines](https://design.visa.com/components/dialog)

### Empty state
Empty states communicate feedback when there’s no information to display and instruct the user on how to move forward. 
<img src="https://design.visa.com/assets/patterns/feedback-and-status/feedback-empty.svg" alt="A message informing users no files have been updated. Get started by uploading a file with an 'Upload file' button."/>
**Usage:** Typically appears the first time a user interacts with a product or page and can be used when data has been deleted or is unavailable. Common uses include: a screen where no files or folders have been created, the resulting screen after completing all tasks in a to-do list manager, an error screen in an instant messaging system when a command isn’t supported, and a filtered or unfiltered search with no results. Don’t default to total empty states, which can cause confusion about whether the system is working.<br/><br/>
**Placement:**  Can appear at the system or site level or within a main workflow or content area.<br/><br/>
**Persistence:** Persists until data is available to display.

### Flag
Flags provide simple, contextual feedback to inform the user of non-critical information that does not require specific attention or action, and does not prevent usage of the workflow.
<img src="https://design.visa.com/assets/patterns/feedback-and-status/feedback-flag.svg" alt="A flag informing users system upgrades are complete."/>
**Usage:**  Primarily used for low priority messages such as confirmations of tasks and success messages related to the page or workflow.<br/><br/>
**Placement:**  Floats over the page in a consistent screen area (top or bottom of a window or page) without blocking vital or interactive content.<br/><br/>
**Persistence:** Should persist passively until the user takes action or dismisses. <br/><br/>
[Explore flag guidelines](https://design.visa.com/components/flag)

### Section message (error and warning)
Error and warning section messages provide contextual feedback on a user action that was just taken that requires additional action. 
<img src="https://design.visa.com/assets/patterns/feedback-and-status/feedback-section-message.svg" alt="An error section message informing users to enter a valid email address and a warning section message informing users their file has unsaved changes."/>
**Usage:**  Limit use of error and warning section messages to critical and high priority messages to highlight potential issues relevant to the user’s workflow.<br/><br/>
**Placement:**   Appears above the section of the page the user is interacting with, usually below the page title, and does not block any information. <br/><br/>
**Persistence:** Should persist until the user takes action (corrects the issue) or dismisses the message.<br/><br/>
[Explore section message guidelines](https://design.visa.com/components/section-message)

## Status component examples
Status messaging doesn’t typically require user action to occur. Instead, these alerts are usually passive, meaning users can view it when they need it. The messaging describes the condition or state of a system or item within a system at a particular time. 

### Badge
Badges are a supplementary component that communicates contextually relevant information about the status of an element or something relevant to the user’s workflow.
<img src="https://design.visa.com/assets/patterns/feedback-and-status/status-badge.svg" alt="Messaging badges placed next to page content."/>
**Usage:**  Primarily used to provide various status updates from low to critical priority in lists, dashboards, data tables, data visualizations, and network diagrams.<br/><br/>
**Placement:**   Placed alongside the element it’s supporting or highlighting.  <br/><br/>
**Persistence:** Not interactive and cannot be dismissed by the user. <br/><br/>
[Explore badge guidelines](https://design.visa.com/components/badge)

### Banner
Banners provide messaging that communicate changes to information on the state or status of a website or app at the global level that is relevant to the user.
<img src="https://design.visa.com/assets/patterns/feedback-and-status/status-banner.svg" alt="An informational banner informing users of their timezone changing."/>
**Usage:** Primarily used to provide updates from low to critical priority where high and critical priority messages may require action and low to medium messages may feature a call to action to learn more or complete a minor task.<br/><br/>
**Placement:** Fills the width of the page at the site or application level.<br/><br/>
**Persistence:** Can persist passively, requiring no immediate action (low and medium priority) or persist until the user takes required action (high and critical priority).<br/><br/>
[Explore banner guidelines](https://design.visa.com/components/banner)

### Progress bars and indicators
Progress bars and progress indicators communicate real-time status updates including the duration and progression of a process towards completion.
<img src="https://design.visa.com/assets/patterns/feedback-and-status/status-progress.svg" alt="A progress bar showing users the percentage status of their upload."/>
**Usage:** Typically used to indicate how much longer a user will need to wait, or in some cases, indicate indeterminate progression when there’s no predetermined end. Common uses include download, file transfer, and installation.<br/><br/>
**Placement:** Depends on the type of progress indicator used.<br/><br/>
**Persistence:** Not interactive; persists until progress is complete. <br/><br/>
[Explore progress guidelines](https://design.visa.com/components/progress)

### Section message (informational)
Informational section messages communicate contextual changes in a state or status updates that typically don’t require any additional action. Can feature a call to action to learn more, undo, or complete a minor task.
<img src="https://design.visa.com/assets/patterns/feedback-and-status/status-section-message.svg" alt="A section message informing users that collaborators now have editing privileges."/>
**Usage:** Limit use of informational section messages to low priority messages that passively communicate relevant information.<br/><br/>
**Placement:** Appears above the section of the page the user is interacting with and does not block any information. <br/><br/>
**Persistence:** Should persist until the user takes action (if applicable) or dismisses the message. <br/><br/>
[Explore section message guidelines](https://design.visa.com/components/section-message)

## Visual indicators
Visual indicators can be used to reflect the urgency or priority of an alert or message. Typically, this includes set colors and icons to grab the user’s attention and draw focus where the the alert or message is placed within the experience. For badges, this also includes stable colors and icons.
- **Low attention:** Indicate when something’s ready to view or to signify that there’s been a change since the last interaction. For example, information or subtle messages that relay status or added details about a system or app.
- **Medium attention:** Indicate when no immediate user action is required or to confirm a user action. For example, success messages that confirm an action after task completion.
- **High attention:** Indicate status change or that user action is required BEFORE someone takes action to avoid the loss of data or an error. For example, warning messages that confirm risky action like changing permissions. 
- **Critical attention:** Indicate when user action is needed immediately to address an issue including irregularity in the system,  malfunctions, invalid entries, and more. For example, error messages that tell users a problem has occurred.

Visual indicators with columns for indicators, type, user attention required, and usage. The indicator column shows an icon and colors for background.

- Indicators: Subtle
- Type: Low
- User attention required: Indicate minor difference from the default state in a badge

- Indicators: Info (informational, neutral, default)
- Type: Low
- User attention required: Indicate important information

- Indicators: Positive (success, stable)
- Type: Medium
- User attention required: Indicate important information

- Indicators: Warning
- Type: High
- User attention required: Indicate a change in status that requires attention

- Indicators: Negative (error, critical)
- Type: Critical
- User attention required: Indicate high priority situations, errors, or critical status

<br/>
Learn more about using icons in [Icons and illustrations](https://design.visa.com/components/icons-illustrations/usage) and messaging color sets in [Color](https://design.visa.com/base-elements/color/usage).

## Level of disruption
Disruption is typically determined by the placement and persistence of the alert or message and describes the interruption experienced by the user. Some components are more disruptive than others while some are passive, meaning the user can view the message when relevant. Disruption can also occur when drawing focus to the alert using visual indicators like color and icons, and words that communicate urgency. <br/><br/>

<img src="https://design.visa.com/assets/patterns/feedback-and-status/level-of-disruption.svg" alt="A scale showing a component's level of disruption from low to high disruption. In order of low to high disruption is progress bar, badge, flag, section message, banner, and dialog. "/> <br/><br/>

For example, a high level of disruption would be a dialog used to communicate that a critical update is needed to continue using an app. The dialog would disrupt the user’s experience, preventing them from continuing to use the app until the user takes action. The visual indicators would draw the user’s focus using red or yellow colors and error or warning indicators, and the words used would communicate the requirement to proceed. <br/><br/>
For guidance on how to word messaging to draw user attention, visit our guidance on [Messaging](https://design.visa.com/content/messaging).


---

# accessibility

---
title: File upload
description: "Accessibility guidance for file upload patterns including best practices, ARIA attributes, and VGAR requirements."
meta_description: "File upload accessibility guide covering landmarks, attributes, and requirements for creating inclusive file upload experiences."
thumbnail: assets/patterns/file-upload-graphic.svg
tab_order: 3
---

## Best practices

Follow general best practice guidance to create accessible experiences for users of all abilities.

- Always include a “Select file(s)” button which can be accessed and activated using the keyboard. Drag and drop is a mouse-dependent operation, and is not accessible with keyboard-only navigation.
- Clearly communicate that automatic uploads immediately initiate file uploads to the server using the description or file input button.

### File uploader

- Indicate that uploading a file is mandatory before proceeding using `aria-required` or `required`.
- Use `aria-roledescription` to provide a more specific description of the dropzone’s function beyond its default semantic role. This helps screen readers clearly convey context to users.
- Use `role='status'` to create a non-obtrusive `live` region for announcing important asynchronous updates, such as file uploads or failures. Avoid frequent updates to prevent overlapping or missed announcements.
- Use a [section message](https://design.visa.com/components/section-message) to provide updates on files that have failed to update. Simplify keyboard navigation by using an inline link to the retry button of the file that’s in error.
- Use a `Dialog` for manual file upload patterns to let the users interact with the list of files marked for upload.

### File card
- Use `aria-describedby` to associate descriptive information, such as  error messages, with elements like file name and file size using an ID reference list. This helps screen readers convey additional context to users.
- Use `aria-label` to provide an accessible name when visual labels aren’t sufficient. This can also identify inline actions represented by icons.
  - Success badges will be announced as “Successfully uploaded [File name].”
  - Reload icon will be announced as “Retry uploading [File name].”
  - Delete icon will be announced as “Delete [File name].”
- Identify determinate progress indicators with `role=progressbar`.
- Use a [table](https://design.visa.com/components/table) component to display files and their upload statuses for dense UIs.



---

# index

---
title: File upload
description: An interactive element that combines a file uploader with file cards to enable users to upload and manipulate files.
meta_description: Learn how to use interactive elements that enable users to upload and manipulate files.
page_size: full-width
thumbnail: assets/patterns/file-upload-graphic.svg
tab_title: Code
show_table_of_contents: false
examples:
  - slug: 'automatic-file-upload'
    title: 'Automatic file upload'
  - slug: 'manual-file-upload'
    title: 'Manual file upload'

---

<LibraryCardListLarge>
    <LibraryCardLarge
        title="Automatic file upload"
        description="Drag-and-drop file upload with automatic processing and real-time status updates."
        href={`https://design.visa.com/patterns/file-upload/automatic-file-upload`}
        thumbnail={`https://design.visa.com/assets/patterns/file-upload/file-upload-multi-file.svg`}
        hasChevron
        hoverColor={colorGreen}
    />
    <LibraryCardLarge
        title="Manual file upload"
        description="File upload that requires user confirmation before processing selected files."
        href={`https://design.visa.com/patterns/file-upload/manual-file-upload`}
        thumbnail={`https://design.visa.com/assets/patterns/file-upload/file-upload-manual.svg`}
        hasChevron
        hoverColor={colorGreen}
    />
</LibraryCardListLarge>


---

# task-flows

---
title: File upload
tab_title: Task flows
description: An interactive element that combines a file uploader with file cards to enable users to upload and manipulate files.
meta_description: Learn about the steps users take to upload and manipulate files.
thumbnail: assets/patterns/file-upload-graphic.svg
tab_order: 1

---

Task flows refer to the steps users progress through when interacting with patterns. They’re based on specific scenarios and demonstrate how users can successfully perform tasks within each pattern layout. To find prototypes for the task flow examples shown on this page, visit the [Task flows (internal only)](https://bookmarks.visa.com/vpds-task-flows-file-upload)<!-- aria-label="task flows (internal only, opens in a new tab)" -->.

## Task flow types

There are two main file upload task flows: manual and automatic upload. Select the task flow that best matches your use case and product requirements. <br/><br/>

**Note:** Any of the task flows below can be adjusted to use the default uploader component or the drag and drop component based on design needs, use case, or product preferences. For more information, reference the [File upload guidelines](https://design.visa.com/patterns/file-upload).

### Automatic file upload

An automatic file upload begins immediately once a user selects a file from their OS file browser or drops it in the drop zone. Once files are selected, they’re generally represented with file cards underneath the uploader component. Unlike manual uploads, the files are transferred to the server immediately.<br/><br/>

**Note:** This is the recommended method as it provides the simplest experience and aligns with user expectations.
<img src="https://design.visa.com/assets/patterns/file-upload/fileupload-auto.svg" alt="A file automatically uploaded to the server when it is dropped in the drag and drop zone."/>

- Clearly communicate that files will be uploaded automatically using labels and inline messaging.

### Manual file upload

In a manual file upload, users select the files they want to upload by placing them in the drop zone or using the OS file browser. Once files are selected, they’re generally represented by file cards underneath the uploader, but aren’t transferred to the server until the user manually sends them, typically by selecting an "Upload” or “Submit” button.

<img src="https://design.visa.com/assets/patterns/file-upload/fileupload-manual.svg" alt="A dialog displaying uploaded files and an upload button."/>

- Use a modal to enable users to review selected files before manually initiating the upload.

## Feedback flows and status updates

Feedback typically occurs after the user takes an action to help them correct mistakes or guide next steps. Status refers to updates that typically don’t require user action. Both communicate important information to users such as errors and success. <br/><br/>

Feedback and status updates can be communicated during file upload flows to ensure users are aware of their upload status. <br/>

- Reference [Forms](https://design.visa.com/patterns/forms) to learn more about form validation, as forms are a key part of a wizard flow.
- Reference [Feedback and status](https://design.visa.com/patterns/feedback-and-status) to learn more about communicating feedback and status.
- Reference [Messaging](https://design.visa.com/content/messaging) for guidance on crafting content within alert messages.

### Incorrect file type or size

In this flow, the user selects files that don’t meet the file type or size requirements. Feedback should be provided as soon as the system recognizes the files don’t meet the requirements.
<img src="https://design.visa.com/assets/patterns/file-upload/fileupload-incorrect-file.svg" alt="A file that failed to upload due to incorrect file type and size."/>

- Use an inline error message to call attention to the error and help the user correct it quickly.
- Clearly specify file requirements to reduce the likelihood of this error occurring.

### No files selected

In this flow, the user attempts to initiate an upload without selecting files. Feedback should be provided as soon as the system recognizes no files were selected.
<img src="https://design.visa.com/assets/patterns/file-upload/fileupload-no-files.svg" alt="An error section message informing users that no files are selected."/>

- Use a [section message](https://design.visa.com/components/section-message/usage) to call attention to the error and help the user correct it quickly.

### Number of selections exceeds limit

In this flow, the user selects too many files for upload. Feedback should be provided as soon as the system recognizes too many files were selected.
<img src="https://design.visa.com/assets/patterns/file-upload/fileupload-exceed.svg" alt="An error section message informing users that the number of selections exceed the limit."/>

- Use a [section message](https://design.visa.com/components/section-message) to call attention to the error and help the user correct it quickly.
- Clearly specify how many files can be uploaded to reduce the likelihood of this error occurring.
- Limit the number of files that can be selected in the OS file browser when possible.
- Do not upload any files until the error is corrected.

### Multiple files with errors

In this flow, multiple files have errors. They may all have the same error or independent ones. Feedback should be provided as soon as the errors are recognized.
<img src="https://design.visa.com/assets/patterns/file-upload/fileupload-mult-errors.svg" alt="An error section message listing the files in error."/>

- Use a [section message](https://design.visa.com/components/section-message) to call attention to the error and help the user correct it quickly.
- Use an error state and inline message for each file that failed to upload.

### Duplicate file selected

In this flow, the user selects the same file for upload twice. Feedback should be provided as soon as the duplicate selection is recognized.

<img src="https://design.visa.com/assets/patterns/file-upload/fileupload-duplicate.svg" alt="A warning dialog informing users that they've selected a duplicate file and asking if they would like to replace the file."/>

- Use a [dialog](https://design.visa.com/components/dialog) to inform the user of the error and include relevant actions such as replacing or renaming the duplicate file.

### Network errors

In this flow, network or connectivity errors prevent files from uploading. This status update should be provided immediately in the form of an error.  
<img src="https://design.visa.com/assets/patterns/file-upload/fileupload-network.svg" alt="A banner informing users of network issues."/>

- Use a [banner](https://design.visa.com/components/banner) to notify users of the error and explain the relevant next steps.
- Use an error state and inline message for each file that failed to upload.

## Communicating success

Success confirmations indicate that files uploaded successfully. The file card component includes a circular progress indicator that shows a success state upon completion. If your design uses an alternate file display, ensure status is communicated through another accessible method.  <br/>

- Reference [Feedback and status](https://design.visa.com/patterns/feedback-and-status) to learn more about communicating success.
- Reference [Messaging](https://design.visa.com/content/messaging) for guidance on crafting content within success messages.

<img src="https://design.visa.com/assets/patterns/file-upload/fileupload-success.svg" alt="A success flag informing users that their upload is complete."/>

- Consider adding a [flag](https://design.visa.com/components/flag) to inform users when all files have uploaded successfully. This is especially helpful during multi-file uploads.


---

# usage

---
title: File upload
tab_title: Usage
description: An interactive element that combines a file uploader with file cards to enable users to upload and manipulate files.
meta_description: Learn how to use interactive elements that enable users to upload and manipulate files.
thumbnail: assets/patterns/file-upload-graphic.svg
tab_order: 2
keywords: ["File input", "file selection", "file picker", "media uploader"]
related: 
  components: 
    - button
    - progress
---

The file upload pattern combines [file uploader](https://design.visa.com/patterns/file-upload/usage#file-uploader), [file card](https://design.visa.com/patterns/file-upload/usage#file-cards), and [button](https://design.visa.com/components/button) components with other context-dependent components to enable users to upload files from their device to a platform, server, or [form](https://design.visa.com/patterns/forms). <br/><br/>

Also known as: File input, file selection, file picker, media uploader.

## Anatomy

<img src="https://design.visa.com/assets/patterns/file-upload/fileupload-anatomy.svg" alt="A file uploader with callout A indicating the required uploader title, callout B indicating the optional uploader description, callout C indicating the required select file(s) button, callout D indicating the optional drag and drop zone, callout E indicating the optional file card thumbnail, callout F indicating the required file card name, callout G indicating the optional file size, callout H indicating the required file card progress indicator, callout I indicating the required delete icon button, and callout J indicating the optional submit button"/>
**A. Uploader title (required):** Brief text indicating the uploader’s function.<br/>
**B. Uploader description (optional):** Brief text providing upload instructions or file requirements.<br/>
**C. Select file(s) button (required):** Button that opens the system’s file browser so users can select a file.<br/>
**D. Drag and drop zone (optional):** Outlined container enabling users to place files for upload.<br/>
**E. File card thumbnail (optional):** Icon or compressed image indicating the file type.<br/>
**F. File card name (required):** Text communicating the file name as indicated by the user’s device.<br/>
**G. File size (optional):** Text indicating the size of the file.<br/>
**H. File card progress indicator (required):** Circular progress indicator showing the upload status.<br/>
**I. Delete icon button (required):** UI icon button enabling users to remove a selected file.<br/>
**J. Submit button (optional):** Button enabling users to submit successful uploads.<br/>

## Usage

When to use and when not to use different types of file upload patterns

- Pattern: To help users identify and perform quick actions on files they’ve selected for upload. <br/><br/> To communicate upload progress.
- When to use: In interfaces with limited space or specific design requirements.

- Pattern: To accommodate uploaders placed in compact interfaces with specific design requirements.
- When to use: When there’s sufficient space to represent selected files with cards.

## Best practices

- Follow all guidance and best practices for implementing [file uploaders](https://design.visa.com/patterns/file-upload/usage#file-uploader) and [file cards](https://design.visa.com/patterns/file-upload/usage#file-cards).
- Only include one file uploader per page or interface to avoid overwhelming users.
- Follow guidance for [buttons](https://design.visa.com/components/button) when implementing calls to action within file upload patterns.
- Specify accepted file types and sizes to prevent errors and avoid frustration.
- Use clear language to indicate whether users can upload multiple files or just one.
- Allow users to cancel or delete a file at any point in the file upload process.
- Always accept as many file types and sizes as possible based on server capabilities.

### File uploader

File uploaders allow users to select and upload files from their device to a specific location, such as a server. They’re often used in forms, but can also appear as standalone elements.

  
    #### Default (drag and drop)

    The drag-and-drop method enables users to upload files by placing files in the drop zone or using their OS browser.
    <img src="https://design.visa.com/assets/patterns/file-upload/file-uploader-do-1.svg" alt="A file uploader with a drag and drop zone"/>
    - Use this for desktop applications when there’s sufficient space to accommodate the drop zone. 
    - Follow best practices in the [Drag and drop zone section](https://design.visa.com/patterns/file-upload/usage#drag-and-drop-zone) to ensure this method is accessible for all users. 
  
  
    #### Button only

    The button-only method enables users to upload files with their OS browser without drag-and-drop functionality.
    <img src="https://design.visa.com/assets/patterns/file-upload/file-uploader-dont-1.svg" alt="A file uploader with just a button"/>
    - Use this method for mobile applications or if space is limited. 
    - Use this method if the uploader is placed within other elements or crowded interfaces.
  

### File cards

File cards are visual representations of files selected for upload. They display important information like the file name, upload status, and key actions like retry or delete.

- Provide clear feedback about the status of a file, like whether it’s still uploading, failed to upload, or successfully uploaded.
- Include relevant inline actions such as retry or delete to enable users to quickly manipulate selected files.

#### File card order

In general, it’s best to display file cards in the order they’re selected in the OS file browser or placed in the drop zone. This supports findability and is generally the simplest method for ordering files.

<img src="https://design.visa.com/assets/patterns/file-upload/fileupload-order.svg" alt="A file uploader with file cards shown in the same order they appear in the file browser"/>

- Avoid changing the order of file cards whenever possible, as this can disorient the user.

#### File thumbnails

File thumbnails can be used to help users quickly identify the type of file being uploaded or display a compressed version of the selected media. There are two types of file thumbnails: file icons and compressed image previews.<br/><br/>
**Note:** Including file thumbnails increases the server load during file processing. Product teams should work closely with their developers and designers to determine the correct method for their specific use case.

#### Inline actions

Inline actions can be added to file cards to enable users to directly manipulate individual files. Common actions include download, retry, or rename. File cards should always include actions that enable users to cancel or delete their upload. This helps prevent mistakes and gives users control over their experience.

#### Progress indicators

File cards include progress indicators to communicate the status of an upload. If the upload fails, the progress indicator is replaced with an inline action enabling the user to try again. When the upload completes, the progress indicator shows a success state. This ensures users are aware of the status of their upload.

<img src="https://design.visa.com/assets/patterns/file-upload/filecard-progress.svg" alt="A file card that's loading, a file card in a success state, and a file card in an error state with the action to retry the upload"/>

- Use an [indeterminate progress indicator](https://design.visa.com/components/progress/usage#indeterminate-progress) to communicate upload status.

### UI icon buttons

File upload patterns can be prompted with a UI icon button when space is limited. This method should work like the default file uploader and prompt the user to select a file using their OS file browser.

- Don’t use icon buttons to prompt a drop zone.

### Single-file uploads

File uploaders can support single or multi-file uploads. Single-file uploads allow users to select and upload one file at a time. They’re typically used when only one file is required from the user, like profile photos, applications, or forms.

<img src="https://design.visa.com/assets/patterns/file-upload/fileupload-single.svg" alt="A file uploader that only allows single file uploads."/>

- Use clear messaging to indicate that only one file can be submitted for upload.
- Replace the “Select file(s)” button with a file card to provide a clear visual cue that only one file can be uploaded. This helps prevent errors by signaling that additional files can’t be selected.
- Remove the select file(s) button and/or the drop zone after the user selects a file. This helps prevent errors by signaling that additional files can’t be selected.

### Multi-file uploads

File uploaders can also support unlimited uploads, or limit selections to any specific number. This is typical when users need to upload several files at once, such as multiple photos in an album, documents for a project, or records to a database, but the number of files is not too large. In this scenario, files are manually selected by the user, and the server processes each file individually.

<img src="https://design.visa.com/assets/patterns/file-upload/fileupload-multi.svg" alt="A file uploader that allows multi-file uploads."/>

- Use clear messaging to indicate how many files can be submitted for upload.
- Consider adding controls to enable users to “Select all” or “Delete all” files selected. This is particularly helpful when users are expected to upload many files at once.

#### Adding additional files

Users should always be able to add additional files for upload after their initial selection. At any point in the process, the “Select file(s)” button or drop zone should remain active to ensure users can select more as needed. <br/><br/>
New file cards can be placed before or after existing ones. Whichever method you choose, implement it consistently.

<img src="https://design.visa.com/assets/patterns/file-upload/fileupload-add.svg" alt="Additional file cards added below the previously selected files."/>

- Keep any files the user already selected to ensure a seamless experience and avoid frustration.

#### Alternate labels  

File upload patterns should always have a title or label clearly indicating their purpose. While the uploader component includes a title in the build, hiding it can provide design flexibility or space for more context. If the title within the component build is hidden, include an alternate label or provide enough context clues to explain the purpose of the uploader.

<img src="https://design.visa.com/assets/patterns/file-upload/fileupload-label.svg" alt="A form with a file uploader component, showcasing the flexibility of using alternate labels and styles in place of the title that is in the file uploader build."/>

- Always include the title programmatically for accessibility to ensure screen reader users can identify the file uploader.

## Layouts

The file upload pattern has multiple layouts to accommodate different visual designs and use cases. Each can be used as a starting point to enable different task flows. To learn about the file upload task flows and how they work with each pattern, visit the [Task flows tab](https://design.visa.com/patterns/file-upload/task-flows). <br/><br/>
**Note:** Any layout can be created with both the default uploader component or the drag and drop component.

### With file cards

[File cards](https://design.visa.com/patterns/file-upload/usage#file-cards) are visual representations of files selected for upload and are the default method for representing files selected for upload. They're placed between the uploader component and the optional "Submit" button to ensure the user can easily access the files they've selected, understand the upload status, and perform quick actions. This layout can be placed within various contexts or interfaces, like in a form.
<img src="https://design.visa.com/assets/patterns/file-upload/fileupload-with-cards.svg" alt="A file upload pattern placed inside a form, using file cards to represent individual files."/>
- Use secondary button styling in the file uploader component so it doesn’t conflict with other primary buttons in the interface.

### With alternate file display

Some scenarios require alternate file displays if the use case or design can’t accommodate file cards. This layout provides flexibility for alternate file representations, such as files that are listed in table rows. This layout can be modified or applied in any use case where file cards don’t fit within the interface or context.
<img src="https://design.visa.com/assets/patterns/file-upload/fileupload-alt-display.svg" alt="A file upload pattern used with a dynamic table layout in which each row represents individual files."/>

- Always communicate upload status using a progress indicator and success state.

## Behaviors

File uploaders have various behaviors to help users select and upload files. Reference the guidance below to learn about common behaviors of this component and features you may implement based on use case.

### Upload button

The “Upload” button is an additional call to action used to transfer selected files to the server in manual task flows. This provides extra control and security by allowing users to manipulate file cards before transferring them to the server. This button should not be used in automatic flows. For more information on manual task flows, visit the [Task flows tab](https://design.visa.com/patterns/file-upload/task-flows).
<img src="https://design.visa.com/assets/patterns/file-upload/fileupload-submit.svg" alt="An upload button is used to initiate uploads in a manual file upload flow."/>

- Use clear language such as “Upload” or “Upload files” to ensure the purpose of the button is clear.
- Use primary styling for the “Upload” button to emphasize that files must be manually uploaded.

### Drag and drop zone

The drag and drop zone is a container enabling users to place files from their device to initiate an upload. When the user hovers over the drop zone with files, it displays an active state to indicate it’s ready to receive files. This is an optional element and can be removed to accommodate smaller screens or compact designs.

<img src="https://design.visa.com/assets/patterns/file-upload/file-uploader-drag.svg" alt="A drop zone that shows a file card after a file is dragged and dropped in the zone."/>

- Use active styling when the user hovers above the drop zone to indicate the zone is ready to receive files.
- Add file cards as soon as the user places files in the drop zone to provide quick confirmation that the file was received.
- Always pair a drag and drop zone with an upload button allowing users to select files from their OS file browser instead.

### Drag and drop magnetic effect

The magnetic effect refers to a border around the drag and drop zone allowing users to drop files in a slightly larger area. This can reduce errors by increasing the touch target without requiring more screen space.<br/><br/>
**Note:** Product teams should work closely with their designers and developers to determine how large the magnetic zone should be. In some cases, the magnetic effect can include a slightly larger area than the drop zone. In other cases, teams may choose to include the full screen in the magnetic effect, enabling users to place their file anywhere on the page to initiate an upload. Explore the content below for an overview of common strategies for implementing a magnetic effect.

#### Extended drop zone

An extended drop zone can be used to slightly extend the drop zone. When the enters the extended drop zone, it displays an active state to indicate they can drop the file to initiate an upload.<br/><br/>
**Note:** In the visual below, the pink border is shown to help illustrate the active drop zone, but appearance will vary based on your use case and design.

<img src="https://design.visa.com/assets/patterns/file-upload/file-uploader-drag-magnetic.svg" alt="A drag and drop zone becomes active when a file is dragged within the extended drop zone but not within the actual drop zone."/>

- Use a visual indicator to communicate to users that the drop zone is active on hover.

#### Full page drop zone

A full page drop zone extends the magnetic effect to cover the full content area of a page. containing the drop zone. When the user hovers over the page with a file, borders appear with a section message indicating they can drop the file to initiate an upload.

<img src="https://design.visa.com/assets/patterns/file-upload/file-uploader-drag-full.svg" alt="A full page drag and drop zone"/>

- Use an overlay or other visual indicator to ensure it’s clear that the drop zone is active.
- Include a section message on the page indicating files can be dropped.

### OS file browser

The OS file browser refers to the default file browser in the user’s system. When users select the "Select files(s) button," the OS file browser dialog is automatically prompted.

<img src="https://design.visa.com/assets/patterns/file-upload/file-uploader-os.svg" alt="A user clicks on the file uploader button and the OS file browser dialog is prompted"/>

- Disable unsupported file types in the OS file browser when possible to prevent users from selecting invalid files and reduce the chance of errors.

## Platform considerations

### Mobile

When implementing file uploaders on mobile platforms, use the default variant without the drag and drop zone to save space and enhance usability.
<img src="https://design.visa.com/assets/patterns/file-upload/fileupload-mobile.svg" alt="File upload in a mobile layout."/>

- Allow users to upload from their file system or directly from their camera gallery.
- Always ask for permission before accessing the user’s camera gallery.

## Content

- Use sentence case for all content except proper nouns or acronyms.
- Avoid abbreviations, acronyms, or jargon unless they’re commonly understood or necessary.
- Indicate the purpose of the drag and drop zone with clear text like “Drag and drop files”.

### Title  

- Don’t include punctuation.
- Limit the title to two or three words.
- Indicate the purpose of the element by using clear language like “Upload files” or “Attach files”.

### Description

- Use full sentences with proper punctuation.
- Specify the number of files that can be uploaded, accepted file types, and size limits.

### Calls to action

- Follow [Button guidelines](https://design.visa.com/components/button) for help crafting content in calls to action.
- Include a verb like “Select” in the uploader CTA label to clearly indicate the button enables users to select files. For example, use labels like “Select attachments” or “ Select files from folder”.
- Use clear language to indicate the purpose of the manual upload button such as “Submit” or “Upload”.

### File cards

#### File name

- Ensure the file name matches how it’s displayed in the user’s system.
- Include the file type extension at the end of the file name.

#### File size

- Include the file size without a space between the number and unit abbreviation. For example, use “10MB”.


---

# index

---
title: Filters
tab_title: Usage
description: Controls enabling users to refine results in lists, tables, content cards, and charts by applying specific criteria.
meta_description: Learn how to use controls enabling user to refine results by applying specific criteria.
thumbnail: assets/patterns/filters/dropdown-filter.svg
tab_order: 2
keywords: ["filtering", "filter"]
related: 
  components: 
    - chips
    - listbox
  patterns:
    - dynamic-table
---

Filters refine the results in [lists](https://design.visa.com/components/listbox/usage), [tables](https://design.visa.com/components/table/usage), [content cards](https://design.visa.com/components/content-card/usage), and [charts](https://design.visa.com/data-visualization/charts/overview) by including or excluding items based on specific criteria, so only the most relevant information is presented. <br/><br/> 

Also known as: Filtering.

## Anatomy
<img src="https://design.visa.com/assets/patterns/filters/filters-anatomy.svg" alt="Dropdown filters titled Saved filters, Filter type, and Status and a button labeled Show all filters followed by chips showing selected filters. Callout A Saved filters menu, callout B Filter category, callout C Applied filter indicator, callout D Show all filters button, callout E Applied filter chip, callout F Clear all filters button, callout G Filter option, callout H Apply button, and callout I Clean button."/>
**A. Saved filters menu (optional):** Button displaying a user’s saved filter sets. <br/>
**B. Filter category (required):** Brief text describing the general property of a group of items. <br/>
**C. Applied filter indicator (required):** Indicates the number of applied filters within a category.<br/>
**D. Show all filters button (optional):** Button that launches a dialog displaying all available filters.<br/>
**E. Save filters button (optional):** Button that saves the applied filters as a saved set of filters.<br/>
**F. Applied filter chip (required):** Chip representing selected filter options.<br/>
**G. Clear all filters button (required):** Button that removes all selected filters across categories and reset results to default.<br/>
**H. Filter option (required):** Individual value or range of values within a filter category.<br/>
**I. Apply button (required):** Button that applies selected filter options.<br/>
**J. Clear button (optional):** Button that clears the selected filter options within a category.

## Usage
- Pattern: For interfaces with lightweight to medium filtering needs where users need to apply individual or batch filters.
- When to use: For data-heavy applications that require an API call when a filter is applied. Use advanced search instead.

- Pattern: For complex interfaces where users are applying several filters in a batch.
- When to use: For interfaces with light filtering needs.

- Pattern: For shopping experiences or other layouts where results are represented as content cards.
- When to use: For interfaces that use [vertical navigation](https://design.visa.com/components/vertical-navigation/usage). <br/><br/> If displaying filtered data in a complex [dynamic table](https://design.visa.com/patterns/dynamic-table). Use dropdown filters, advanced search, or in-table filters instead.

- Pattern: For interfaces with limited space where users are applying batch filters. <br/><br/>For responsive interfaces.
- When to use: For complex interfaces where users may need to edit filters frequently. Use dropdown filters, advanced search, or in-table filters instead.

- Pattern: For complex dynamic tables where users need to refine results within the context of the table.
- When to use: For layouts outside of a dynamic table. <br/><br/> For lightweight or consumer interfaces. <br/><br/> For mobile applications.

## Best practices
- Organize filters in a logical order, such as placing the most frequently used at the beginning.
- Always show a summary of active filters at the top of the results area. 
- Provide an intuitive way for users to clear filters individually or to reset results to their default values.
- Clearly indicate which filters are currently active or selected, through [badges](https://design.visa.com/components/badge/usage) and [chips](https://design.visa.com/components/chips/usage).

### Filtering methods
Filtering methods refer to the different ways users can refine choices in their product experience. These methods can be used within any of the layouts. There are various methods available through this pattern including single-select filtering, multi-select filtering, and filtering with free text input.

#### Single-select filtering
Single-select filtering is used when only one filter option can be selected from a filter category. Users are limited to a single choice from a predefined group of values. The following components can be used with this filtering method. 

  
    ##### Combobox

    Comboboxes combine a single-line input and menu, enabling the user to search a limited set of options by typing a value into the field.
    <img src="https://design.visa.com/assets/patterns/filters/filter-combobox.svg" alt="Combobox filter with menu"/>
    <br/>
    [Explore Combobox guidelines](https://design.visa.com/components/combobox/usage)
  
  
    ##### Select (native)

    Select (native) uses the native default select in a browser, enabling users to select one option from a set of multiple, related options in a dropdown list.
    <img src="https://design.visa.com/assets/patterns/filters/filter-select.svg" alt="Select (native) filter with menu"/>
    <br/> 
    [Explore Select (native) guidelines](https://design.visa.com/components/select/usage)
  

  
    ##### Single-select listbox

    Single-select listboxes display all available options in a scrollable list, and enables users to select one option.
    <img src="https://design.visa.com/assets/patterns/filters/filter-listbox.svg" alt="Listbox filter example"/>
    <br/>
    [Explore Listbox guidelines](https://design.visa.com/components/listbox/usage)
  
  
    ##### Dropdown menu with sinlge-select listbox

    Dropdown menus with single-select listboxes use a temporary listbox to reduce clutter.
    <img src="https://design.visa.com/assets/patterns/filters/filter-dropdown.svg" alt="Dropdown button with listbox menu"/>
    <br/>
    [Explore Dropdown menu guidelines](https://design.visa.com/components/dropdown-menu/usage)
  

#### Multi-select filtering
Multi-select filtering is used when more than one filter option can be selected, either within a filter category or across multiple categories. Users can select multiple choices from a predefined group of values. The following components can be used with this filtering method. 

  
    ##### Checkbox

    Checkboxes enable the user to select one or more options from a list where each choice is independent of the other options available in the list. 
    <img src="https://design.visa.com/assets/patterns/filters/filter-checkbox.svg" alt="Checkbox list"/>
    <br/>
    [Explore Checkbox guidelines](https://design.visa.com/components/checkbox/usage)
  
  
    ##### Chips

    Chips are compact, interactive elements that represent an input or option. They often appear in groups to help users filter content or enter data.
    <img src="https://design.visa.com/assets/patterns/filters/filter-chips.svg" alt="List of selected and unselected chips"/>
    <br/>
    [Explore Chips guidelines](https://design.visa.com/components/chips/usage)
  

  
    ##### Multiselect

    Multiselect enables users to search and select multiple options from a list when space is limited. The dropdown list only appears when the user begins to type. 
    <img src="https://design.visa.com/assets/patterns/filters/filter-multiselect.svg" alt="Multiselect dropdown and menu"/>
    <br/>
    [Explore Multiselect guidelines](https://design.visa.com/components/multiselect/usage)
  
  
    ##### Multi-select listbox

    Multi-select listboxes display all available options in a perisistent, scrollable list and enables users to select multiple options.
    <img src="https://design.visa.com/assets/patterns/filters/filter-multiselect-listbox.svg" alt="Listbox with multiselct options"/>
    <br/>
    [Explore Listbox guidelines](https://design.visa.com/components/listbox/usage)
  

  
    ##### Dropdown menu with multi-select listbox

   Dropdown menus with multi-select listboxes use a temporary listbox to reduce clutter. Users can select one or more options from a dropdown list. 
    <img src="https://design.visa.com/assets/patterns/filters/filter-dropdown-multiselect-listbox.svg" alt="Dropdown menu with a listbox menu containing multiselect options"/>
    <br/>
    [Explore Dropdown guidelines](https://design.visa.com/components/dropdown-menu/usage)
  

#### Filtering with free text input
Filtering with free text input is used when users can enter text to specify the criteria for filtering data. This method allows for more flexible and precise control by enabling users to enter custom keywords, phrases, or values directly. The following components and patterns can be used with this filtering method. <br/><br/>
<Typography variant="body-2">**Note:** This method isn’t recommended to be used with in-table filters. Reference [In-table filters](https://design.visa.com/patterns/filters/#in-table-filters) under Layouts for more information.</Typography>

  
    ##### Search field

    A search field is a pattern that enables users to look across a large set of data to find results based on the keywords entered. 
    <img src="https://design.visa.com/assets/patterns/filters/filter-search.svg" alt="Search field"/>
    <br/>
    [Explore Search guidelines](https://design.visa.com/patterns/search)
  
  
    ##### Input

    An input field is a component that enables users to enter text or data to find results for a specific field or filter category.
    <img src="https://design.visa.com/assets/patterns/filters/filter-input.svg" alt="Input field"/>
    <br/>
    [Explore Input guidelines](https://design.visa.com/components/input/usage)
  

  
    ##### Date selector

    Date selectors enable users to type in or select a single date or a range of dates from the past, present, or future. 
    <img src="https://design.visa.com/assets/patterns/filters/filter-date.svg" alt="Date selector"/>
    <br/>
    [Explore Date selector guidelines](https://design.visa.com/components/date-selector/usage)
  

### Loading states
Loading states provide visual feedback that helps users understand that their input is being processed and results will be displayed shortly. This reduces frustration and keeps users informed about the status of their actions. 

#### Progress indicators
<Typography variant="body-2"> [Progress indicators](https://design.visa.com/components/progress/usage) provide a clear visual representation to users that a process is ongoing.</Typography>
<img src="https://design.visa.com/assets/patterns/filters/filter-progress.svg" alt="Filters with a progress indicator"/>
- Use indeterminate progress indicators for unknown or longer loading times or for larger, more complex datasets.

### Displaying filter options
While filters can serve as a powerful tool for some use cases, they don’t need to be presented in all scenarios. Provide users with the flexibility to minimize or show filters as needed to keep the interface uncluttered.
- Show the essential filters first and display the rest behind a “Show all filters” button.
- Use accordions or “Show more” links to enable users to view additional options within filter categories.

### No results
If a filter application fails or there are no filter results available, use meaningful content to explain the situation and give users clear next steps. Reference [Messaging](https://design.visa.com/content/messaging) for guidance in crafting content for empty state messages.
<img src="https://design.visa.com/assets/patterns/filters/filter-no-results.svg" alt="Table filters with no results"/>

## Layouts
The filters pattern has multiple layouts to accommodate different visual designs and user needs. Choose a layout that fits your product’s navigation, the format in which data is presented, and the filtering method being used. For example, if your product’s navigation is horizontal, a horizontal filter layout might integrate more seamlessly and make better use of space. <br/><br/>

Each layout can be used as a starting point to enable different task flows. To learn about the filters task flows and how they work with each layout, visit the [Task flows (internal only)](https://bookmarks.visa.com/vpds-filters-task-flows)<!-- aria-label="task flows (internal only, opens in a new tab)" -->.

### Dropdown filters
This layout represents filter categories as dropdown buttons with listbox or search functionality. As users refine their search by selecting filter options, the selected values appear in a row below the filter categories. This layout can be used with single-select or multi-select filtering methods. 
<img src="https://design.visa.com/assets/patterns/filters/filter-layotus-dropdown.svg" alt="Dropdown filters with selection chips below them and a clear all button"/>
- Use the “Show all filters” button to store additional filters as the screen size gets smaller.
- Enable applied filter chips to wrap to multiple rows if needed.

### Advanced search filters
This layout displays filters as form fields placed side by side, including a search field located above the form fields. The search field enables users to search within the table or dataset as a whole. This layout is best for experiences with large datasets or complex queries, because users can simultaneously set multiple filters across categories. 
<img src="https://design.visa.com/assets/patterns/filters/filter-advanced.svg" alt="Search field with an advanced filters dropdown"/>
- Include separate “Search” and “Apply” buttons if users need the option to use them as distinct functions.

### Filter panel
This layout consists of a persistent vertical panel on the side of the main content area. This layout is best for shopping experiences or other UI applications that display results that reflow easily as the window size reduces. Filters can either be displayed as individual fields or within [accordions](https://design.visa.com/components/accordion/usage) to prevent overwhelming users.
<img src="https://design.visa.com/assets/patterns/filters/filter-panel.svg" alt="Accordion filter panel"/>
- Utilize panels or wider areas effectively to display filters without disturbing the main content area.

### Filter dialog
In this layout, filters are displayed in a temporary dialog activated by a filter button, typically located in an action bar. The dialog closes when the user selects “Apply” or dismisses it by interacting outside the dialog. Selecting outside the dialog without selecting “Apply” will discard any changes. This layout is best for interfaces with limited space where users apply batch filters.
<img src="https://design.visa.com/assets/patterns/filters/filter-dialog.svg" alt="Accordion filters within a dialog"/>
- Use a filter button to activate the modal, and indicate the amount of active filters with a number [badge](https://design.visa.com/components/badge/usage).
- Use [accordions](https://design.visa.com/components/accordion/usage) to represent long lists of options to prevent overwhelming users.

### In-table filters
In-table filters are specifically used in dynamic tables and enable users to refine the table data directly from a menu in the column header. Users can open a dialog by selecting the options button within the header. Selecting “Apply” closes the dialog and applies the chosen filters. Only one table column can be filtered at a time.
<img src="https://design.visa.com/assets/patterns/filters/filter-table.svg" alt="Dynamic table with filterable columns and selection chips shown above"/>
- Always display applied filters outside of the table. 
- Align filter labels with column headings.
- Avoid using open input fields with in-table filtering. Consider using the Advanced search filters pattern instead.

## Behaviors
Filters have various behaviors to help users refine their choices. Reference the guidance below to learn about common behaviors and features you may implement based on use case. 

### Applying filters
There are two ways to apply filters: Using a button and instant filtering. For most use cases, using an “Apply” button is preferred as instant filtering can be disorienting to users if the page results reload anytime a selection is made. In some cases, instant filtering is necessary to improve the overall experience. For example, when clearing an applied filter chip, users may expect that action to happen instantly.

  
    #### Apply button

    The apply button enables users to make selections or adjustments, then confirm their choices by selecting "Apply." 
    <img src="https://design.visa.com/assets/patterns/filters/filter-apply-button.svg" alt="List of accordion filters with an Apply button and a Clear all button"/>
  
  
    #### Instant filtering

    Instant filtering immediately reflects user choices as they make selections, without needing additional confirmation. 
    <img src="https://design.visa.com/assets/patterns/filters/filter-instant.svg" alt="Filter chips with clear icons"/>
  

### Show all filters categories
The “Show all filters” button launches the All filters dialog to display all available filters, including options already displayed in the main view. Displaying all filter categories at once can overwhelm users and push important content off-screen, especially in complex experiences. Filters can be displayed as individual form fields or within [accordions](https://design.visa.com/components/accordion/usage).
<img src="https://design.visa.com/assets/patterns/filters/filter-show-more.svg" alt="Filter panel with accordions containing various filter options"/>
- Preserve any selections made in accordion categories when they’re collapsed.
- Use [badges](https://design.visa.com/components/badge/usage) to display the number of applied filters within the accordion.

### Clearing filters
The “Clear all” button removes all active filters and returns the results to an unfiltered state. Users can clear individual filters by selecting the clear button within the chip. If your application has set default filters, such as a preset date range, consider using a “Reset filters” button instead to give users a way to return to that baseline.
<img src="https://design.visa.com/assets/patterns/filters/filter-clearing.svg" alt="Filter chips with a clear all button"/>

### Sorting results
Sorting helps users find the information they need by organizing data into a preferred order. It can help identify trends, patterns, or anomalies within a dataset. Unlike filtering, sorting only reorders existing data—it doesn’t hide or remove items. Common ways to sort data include alphabetically, numerically, and chronologically.
<img src="https://design.visa.com/assets/patterns/filters/filter-sorting.svg" alt="Blurred filter results shown with a clear, highlighted dropdown menu with options to sort them"/>
- When offering sorting options, provide a default that best fits your use case. For example, if users typically sort alphabetically, make that the default.
- If displaying results in a dynamic table, provide sorting functionality in the column headers. Reference [Dynamic table](https://design.visa.com/patterns/dynamic-table/usage#sorting) for examples.

## Platform considerations

### Mobile
When implementing filters in mobile experiences, use the dropdown filters or filter panel. Dialogs are displayed as panels in mobile layouts.
<img src="https://design.visa.com/assets/patterns/filters/filter-mobile.svg" alt="Filter results shown with a dropdown menu with options to sort them"/>
- Allow selected filter chips to scroll horizontally off-screen instead of wrapping to a new line.
- Display filters as form fields or within accordions, depending on the use case.
- Avoid in-table filtering in mobile experiences.

## Content 
- Use clear, concise text to label filter options and categories.
- Use sentence case for all content except proper nouns or acronyms.
- Limit filter labels to three to five words when possible.
- Follow guidance in [Dynamic table](https://design.visa.com/patterns/dynamic-table) when writing table titles, subtitles, column and row headers labels.
- Reference [Chips](https://design.visa.com/components/chips/usage) for guidance on creating effective filter chip labels.
- Reference [Button](https://design.visa.com/components/button/usage) for guidance on creating effective button labels.

### Column and row headers
- Align filter names with the relevant column header.
- Ensure column headers accurately describe the contents so users can interpret the data without additional context. 

---

# index

---
title: Forms
description: Get guidance on everything from layouts to validation to ensure forms are clear and usable.
meta_description: Learn how to collect data from users with guidance on everything from layouts to validation.
thumbnail: assets/patterns/forms/forms.svg
keywords: ["Form validation"]
related: 
  content: 
    - messaging
  patterns:
    - application-layouts
---

The forms pattern typically combines [input](https://design.visa.com/components/input), [select](https://design.visa.com/components/select), and [button](https://design.visa.com/components/button) components with other context-specific components or patterns like [file upload](https://design.visa.com/patterns/file-upload) to enable users to enter information. For longer forms with four or more steps, reference [Wizard](https://design.visa.com/patterns/wizard).<br/><br/>
Also known as: Form validation.

## Anatomy

<img src="https://design.visa.com/assets/patterns/forms/forms-anatomy.svg" alt="An example form with callout A indicating the form title, callout B indicating the optional form description, callout C indicating the required input field labels, callout D indicating the required inline error message, callout E indicating the optional inline message, and callout F indicating the calls to the action."/>

**A. Form title (required):** Brief statement describing the purpose of the form.<br/>
**B. Form description (optional):** Brief description of the form’s purpose.<br/>
**C. Input field labels (required):** Text indicating the purpose of the field and if the information is required.<br/>
**D. Inline message (optional):** Text communicating format requirements or relevant guidance.<br/>
**E. Calls to action (required):** Button components enabling users to submit the form.

## Usage

  When to use and when not to use different types of forms patterns

- When to use: For simpler forms with fewer than four steps.<br/><br/>If steps are short and don’t require substantial input.
- When not to use: For longer forms with four or more steps. Use a [wizard](https://design.visa.com/patterns/wizard) instead.<br/><br/>If steps are longer and contain complex fields.

## Best practices
- Follow regional and global data regulations and laws. Consult with a Visa compliance expert throughout your process.
- Ensure that people of all abilities can use forms by referring to the [Accessibility](https://design.visa.com/global-accessibility-requirements) and [Inclusive design](https://design.visa.com/about-VPDS/inclusive-design) guidance.
- Offer helpful information based on settings, user profiles, data, tracked usage behavior—or with the user’s permission. 
- Use clear labels and examples to assist users in data entry.
- Reserve open-ended inputs like multi-line text fields for longer responses and match the input field size to the expected length of the entry.
- Communicate errors clearly by letting the user know what happened and give clear next steps.

### Form components
Designing a form requires critical thinking about the context to determine the structure, sequence, and components used. The most common components are outlined below.

#### Input

Input fields allow users to enter text and edit data. The type of input field you use should reflect the length of the content you expect the user to enter. To learn more, reference [Input](https://design.visa.com/components/input).

<img src="https://design.visa.com/assets/patterns/forms/forms-elements-input.svg" alt="Single and multi-line input fields"/>
- Single-line input enables users to input one line of content, for example: name/username, email, date of birth, and more. 
- Multi-line input enables the user to enter multiple lines of content including comments and descriptions which are typically open-ended.

#### Selection controls

Selection controls give users predetermined options to select from. When deciding on a component, consider how many options you need to provide and how many items the user may need to select.

#### Checkbox
             
Checkboxes enable the user to select one or more options from a list where each choice is independent of the other options available in the list.  
                      
<img src="https://design.visa.com/assets/patterns/forms/forms-selection-checkbox.svg" alt="Checkbox group labeled Business type"/>
<br/>      
[Explore Checkbox guidelines](https://design.visa.com/components/checkbox)   

#### Radio
           
Radios enable the user to choose a single option from a list of two, but no more than four different options. If providing more than four options, consider using a [dropdown menu](https://design.visa.com/components/dropdown-menu).

<img src="https://design.visa.com/assets/patterns/forms/forms-selection-radio.svg" alt="Radio group labeled Choose account"/>
<br/>
[Explore Radio guidelines](https://design.visa.com/components/radio)           

#### File upload
             
File upload enables the user to upload single or multiple files in predetermined formats and sizes using a browser or drag-and-drop upload methods.  
                      
<img src="https://design.visa.com/assets/patterns/forms/forms-selection-file.svg" alt="Drag-and-drop file upload"/>
<br/>
[Explore File upload guidelines](https://design.visa.com/patterns/file-upload)   

#### Combobox
           
Comboboxes use a single-line input and menu to enable the user to search for an option within a long, but finite set of options by typing a value into a field.  

<img src="https://design.visa.com/assets/patterns/forms/forms-selection-combobox.svg" alt="Combobox labeled Country with the menu open and a list of countries shown"/>
<br/>    
[Explore Combobox guidelines](https://design.visa.com/components/combobox)           

#### Multiselect
             
Multiselect enables the selection of five or more options when space is limited. If space isn’t an issue, use a checkbox group instead to simplify user interactions.
                      
<img src="https://design.visa.com/assets/patterns/forms/forms-selection-multi.svg" alt="Multiselect menu labeled Select card type with three selections made"/>
<br/>
[Explore Multiselect guidelines](https://design.visa.com/components/multiselect)   

#### Select (native)
           
Select (native) uses the native default select in a browser to enable the selection of a single option from a set of multiple, related options in a dropdown list.  

<img src="https://design.visa.com/assets/patterns/forms/forms-selection-native.svg" alt="Select (native) menu labeled Link bank account with a list of bank options"/>
<br/>
[Explore Select (native) guidelines](https://design.visa.com/components/select)           

### Calls to action
Calls to action (CTAs) guide users toward the next step—whether it’s submitting a form, saving progress, or moving to the next screen. Clear and consistent CTAs help users complete tasks confidently and reduce friction. Keep the order of buttons consistent throughout all product experiences to maximize usability and prevent confusion.

### Client-side validation

Form validation is necessary anytime we accept user input. This ensures that the data entered is in the correct format, falls within a valid range (such as date fields), and isn’t missing information that can lead to errors. When there’s been a mistake or issue, effective and immediate error messaging helps users understand the problem and how to fix it.<br/><br/>
Validation before form submission, also known as client-side validation, is an initial check that ensures all required fields are filled out and in the correct format. This method helps limit frustration experienced by the user because it reduces the need to go back, locate and correct mistakes after filling out a lengthy form.<br/><br/>
**Note:** Client-side validation shouldn’t be used as an exhaustive security measure. Data entered should be validated using both methods because client-side validation only makes it easier for malicious users to bypass security.

#### Validation when the user leaves the field
VPDS recommends validating onBlur, not onFocus for client-side validation. An onBlur event happens when a field loses focus, which happens when the user clicks on, tabs out of it, or does something that makes another field or item within a form the active element.<br/><br/>
If a field is left blank or information is entered incorrectly, an inline error message should display after the user shifts focus to another field. Use inline error messages to help the user notice, locate, and correct the error. Once the error is corrected, the error message underneath the field should immediately disappear. 

<img src="https://design.visa.com/assets/patterns/forms/forms-validation-client-1.svg" alt="Form example where the user inputs an email address and moves on to next field but is shown an error on the email field"/>

### Server-side validation

Once a form is submitted, it’s sent to the server for further validation using one of the server-side scripting languages. After the server-side validation process, feedback is then sent back to the user in the form of a success or error message. Server-side validation is important because it provides additional evaluation of the data entered by the user and helps protect against malicious users.<br/><br/>
It’s important to note that there are a few different scenarios that can lead to a server-side error outside of missing or incorrect user inputs such as problems connecting to the server. 

#### Validation messaging

Server-side validation typically results in a success or error validation message. These messages can be presented using a range of components to indicate if the form was successfully or unsuccessfully validated. When unsuccessfully validated, the messages will generate an error.<br/><br/>

While validation messages are an effective method to draw attention to errors, it shouldn’t be used as the only form of error indication as it forces the user to search for the field in error. Additionally, the message may come out of view forcing the user  to rely on memory to fix the issue.<br/><br/>

For additional context on how to create messaging for section messages commonly used to communicate server-side errors, visit [Messaging](https://design.visa.com/content/messaging).  

#### Server-side validation: Success scenarios

When information is successfully validated on the server side, the user will typically receive a success message. The type of component used to communicate the success depends on your context. We recommend using a [flag](https://design.visa.com/components/flag/usage) if the user is taken to a new page after submission or a [section message](https://design.visa.com/components/section-message/usage) if they receive the success message on the same page. For specific guidance on how to decide on the right component for your context, where to place it, and its level of disruption, visit [Feedback and status](https://design.visa.com/patterns/feedback-and-status).

#### Server-side validation: Error scenarios

Reference the scenarios below to better understand the different types of unsucessful server-side validation that result in error messages.

##### One or more fields in error

One or more fields can be in error when the user submits the form but left required fields blank, entered data in an incorrect format, or both. In this scenario, the user submitted the form but left the email field blank and formatted the phone number field incorrectly.<br/><br/>

The user might have been provided with client-side inline error messages but still submitted the form resulting in the server-side validation error. In the example below, we provided feedback in the form of an error section message highlighting that an error occurred and used inline messages draw attention to the fields in error and tell the user how to fix them.

<img src="https://design.visa.com/assets/patterns/forms/forms-validation-server-1.svg" alt="Form example where the user clicks submit and an error is shown"/>

##### Empty form submission

Generally, VPDS doesn’t recommend disabling the “Submit” button when information is incorrectly formatted or left blank. In this scenario, the user submitted the form without entering an email or phone number, which are required fields. They also didn’t receive client-side inline messages since they didn’t interact with any of the fields before submitting.<br/><br/>

In the example below, we provided feedback in the form of an error section message highlighting that required information is missing and used inline messages draw attention to the fields that need an input.<br/><br/>

**Note:** While this is technically client-side validation, it’s referenced in the server-side error framework.

<img src="https://design.visa.com/assets/patterns/forms/forms-validation-server-2.svg" alt="Form example where the user clicks submit and an error is shown"/>

##### Invalid form page level error

In this scenario, the user has completed the form and the input formatting criteria is correct, but due to security reasons you aren’t allowed to identify exactly which field is mismatched.<br/><br/>

In the sign in example below, we provided feedback in the form of an error section message highlighting that required information is missing and used inline messages draw attention to the fields that need an input.<br/><br/>

**Note:** While this is technically client-side validation, it’s referenced in the server-side error framework.

<img src="https://design.visa.com/assets/patterns/forms/forms-validation-server-3.svg" alt="Form example where the user clicks submit and an error is shown"/>

##### Resubmit form

As mentioned, there are a few different scenarios that can lead to a server-side error outside of missing or incorrect user inputs such as problems connecting to the server, connectivity issues with the software, misconfigured settings, or problems with the code or scripts that run on the server. In this scenario, the user has completed the form and the input formatting criteria is correct but the server is having issues connecting and sending the data successfully.<br/><br/> 

In the example below, we provided feedback in the form of an error section message to communicate that we are experiencing connectivity issues and suggest the user either try to submit the form again or to try again later.

<img src="https://design.visa.com/assets/patterns/forms/forms-validation-server-4.svg" alt="Form example where the user clicks submit and an error is shown"/>

### Optional vs. required labels
Always ensure required fields are clearly labeled. While this may seem repetitive, it helps users scan for necessary information and reduces errors. There are two methods for labeling required fields based on your use case. Whichever method you select, use it consistently across your experiences.<br/><br/>
**Note:** Previous VPDS guidance recommended only marking optional fields. Our guidance has been updated to reflect current [Nielsen Norman Group](https://www.nngroup.com/articles/required-fields/)<!-- aria-label="Nielsen Norman Group (opens in a new tab)" --> recommendations.

                    
              #### “Required” in the label (preferred method)
              
              <Typography variant="body-2">Including “required” within the label ensures it’s easy to find, particularly when instructions at the top might not be visible while scrolling. This method bolsters accessibility for both sighted and non-sighted users.</Typography>  
              
              <img src="https://design.visa.com/assets/patterns/forms/forms-assistance-1.svg" alt="Prefered method- input field labeled Email (required)"/>
              
              - Mark all fields that are required. This ensures you’re as explicit and transparent as possible. 
              - Include “(required)” in field label with a space between the last word and the first parenthesis. 
                 
          
                    
              #### Asterisk in the label (alternative method)
              <Typography variant="body-2">
              Asterisks are commonly used to indicate required fields. The main advantage to using this method is that it doesn’t take up much space, helps users along a common edge, and can be used in addition to formatting hints in the label.  
              </Typography>
              
               <img src="https://design.visa.com/assets/patterns/forms/forms-assistance-2.svg" alt="Alternate method- input field labeled *Email with an note saying * indicates required field"/>
              
                - Always include a legend or key at the top of the content area noting that the asterisk indicates a required field.
                - Place the asterisk at the beginning of the label with a space between the symbol and the first word.
          
    

#### When required is implied
Although it's usually recommended to label required fields, there are cases where it’s implied that the field is required. This is common when there’s a one or two fields fundamental to completing of a task, like the username and password fields on a login screen. In these cases, marking the fields required isn’t necessary but can add additional clarity.

#### Labeling optional fields
It’s not generally necessary to mark which fields are optional. While doing so can support clarity, it also adds unnecessary visual noise. Whatever you choose, apply the choice consistently to avoid confusion.

## Layouts
The form pattern features a single, full-page layout designed to provide a consistent and user-friendly experience. This layout ensures all form elements are easily accessible, promoting a seamless flow from start to finish.

### Full page (default)
The full page default layout offers a straightforward, intuitive structure for all forms. It maximizes space for content ensuring users can focus on completing their tasks without distractions.

<img src="https://design.visa.com/assets/patterns/forms/forms-present-full-page.svg" alt="Graphical representation of a web form that takes up the full page"/>

### Columns

The single-column form design creates vertical momentum and maximizes usability. When possible, avoid using multi-column layouts as this approach may create confusion around the logical sequencing of the fields. However, in some cases, multi-column forms may work well when gathering certain information, such as address entry. When planning your layout, consider the amount of fields, the presentation of the form, and field groupings.

<img src="https://design.visa.com/assets/patterns/forms/forms-present-columns.svg" alt="A form with two fields and a set of buttons to submit and cancel. Next to it is an address form with a set of buttons to submit and cancel."/>

## Content
- Use sentence case for all content except proper nouns or acronyms.
- Reference [Button](https://design.visa.com/components/button) for guidance on button formulas and creating button labels.  
- Follow content guidance in [Input](https://design.visa.com/components/input) when writing inline messages, including errors. 
- Review [Messaging](https://design.visa.com/content/messaging) for specific guidance on how to craft content in success, warning, and error messaging.

### Form titles and subtitles

- Use short, concise, and scannable titles with no punctuation.
- Limit titles to three to five descriptive words. If your title can’t be condensed, consider using a subtitle with your title. 
- Limit subtitles to one to two short sentences with punctuation. 
- Use sentence case for both titles and subtitles. The only exceptions are proper nouns or names. 
- Avoid repeating the same words or phrases across the title and subtitle. If struggling to simplify, omit the subtitle. 
- Use subtitles to describe why the information being collected is relevant or to give instructions about the form as a whole.

### Form labels

- Limit labels to a maximum of three words. 
- Use sentence case and no punctuation. The only exceptions are proper nouns or names. 
- Use plain, concise, and descriptive language to help users understand what the corresponding field means.
- Use parallel structure across labels. Although nouns like first name, last name are typically used, in some contexts it may make sense to use verbs such as “Enter email”, or “Confirm password”. 
- Don’t use placeholder text within the input field instead of a label.
- Avoid abbreviations or jargon that aren’t widely understood by global audiences.

---

# index

---
title: Patterns
page_size: large
description: Explore solutions for common interactions, from application layouts to multi-step tasks like requesting a one-time passcode.
meta_description: Explore combinations of components that solve for common user tasks like uploading a file or requesting a one-time passcode known as patterns.
show_table_of_contents: false
---

<PatternsGrid />


---

# index

---
title: Notification tray
tab_title: Usage
description: Container that lists alerts, updates, and operational messages from the system.
meta_description: Learn how to use containers that list alerts, updates, and operational messages from the system.
thumbnail: assets/components/notif-tray-graphic.svg
keywords: ["Notification center", "system notifications", "notification bar", "system messages"]
related:
  components:
    - banner
    - flag
  patterns:
    - feedback-and-status
  content:
    - messaging
---

{/* INTRO */}
The notification tray pattern combines [badge](https://design.visa.com/components/badge) and [link](https://design.visa.com/components/link) components with text and [icons](https://design.visa.com/components/icons-illustrations) to provide a focused, consistent place for users to access messages within an app or system.<br/><br/>
Also known as: Notification center, system notifications, notification bar, system messages.

## Anatomy
<img src="https://design.visa.com/assets/components/notification-tray/notificationtray-anatomy.svg" alt="A notification tray with callout A indicating the required notifications icon, callout B indicating the optional section label, callout C indicating the optional title, callout D indicating the required message, callout E indicating the optional link, callout F indicating the required active tab visual indicator, callout G indicating the optional timestamp, callout H indicating the optional mark as read button, callout J indicating the icon required for error and warning notifications, and callout K indicating the optional settings icon."/> 
**A. Notification icon (required):** Icon that opens and closes the tray and shows the number of unread notifications.<br/>
**B. Section label (optional):** Header text summarizing the content within the tray or section.<br/>
**C. Title (optional):** Brief text summarizing the purpose and severity of the notification.<br/>
**D. Message (required):**  Descriptive text providing important contextual information.<br/>
**E. Link (optional):** Call to action that provides the user with a direct pathway, used in action-based notifications.<br/>
**F. Active tab visual indicator (required):** Border indicating the current view.<br/>
**G. Timestamp (optional):** Text indicating either relative or absolute time, based on the type of notification.<br/>
**H: View all link (optional):** Link allowing users to view all notifications.<br/>
**I. Mark as read button (optional):** Button that marks all notifications as read.<br/>
**J. Icon (required for error and warning notifications):** Visual indicator communicating the urgency of the notification.<br/>
**K: Settings icon (optional):** Icon allowing users to manage the frequency of non-critical notifications to reduce disruption.

## Usage
When to use and when not to use different types of notification trays

- When to use: For critical alerts requiring immediate user attention. Use a [banner](https://design.visa.com/components/banner), [section message](https://design.visa.com/components/section-message), or [dialog](https://design.visa.com/components/dialog) instead.<br/><br/>
              When high volume could overwhelm users with notifications.<br/><br/>
              For redundant or duplicate notifications that could lead to fatigue.

 ## Best practices
- Enable users to dismiss or mark notifications as read.
- Enable users to customize their notification preferences.
- Include timestamps on each notification to give context on their relevance.
- Ensure the tray is easily accessible from any part of the application.
- Keep notifications in the tray until the user views or takes action on them.
- Follow all guidance found in [Badge](https://design.visa.com/components/badge) and [Link](https://design.visa.com/components/link) when implementing those items within a notification tray.

 ### Action-based notification tray
Action-based trays generally present a list of tasks in the format of a to-do list. They are typically system-generated tasks that require action from the user.
<img src="https://design.visa.com/assets/components/notification-tray/notificationtray-behaviors-actionbased.svg" alt="A notification tray with news feed items"/> 
- Always include a call to action, either in the form of a link or make the entire notification selectable to open the pathway.

### Activity-based notification tray
Activity-based trays are generally presented in the format of a news feed or activity log. They are typically user-generated notifications that communicate edits, changes, or comments to other users.

<img src="https://design.visa.com/assets/components/notification-tray/notificationtray-behaviors-activity.svg" alt="A notification tray with news feed items" style="margin-block-end: 0px;"/> 

- Order notifications by time, with the newest at the top.
- Use more friendly, less formal formats for timestamps such as "1 minute ago," "2 hours ago," or "3 days ago." 
- Include the exact date and time if necessary.
- Reference [Grammar and punctuation](https://design.visa.com/content/grammar) to learn more about formatting date and time.  

### Combination notification tray
Combination trays use patterns from both action-based and activity-based notification trays. They can include system-generated tasks or user-generated notifications that communicate activity from other users in the product or system.

<img src="https://design.visa.com/assets/components/notification-tray/notificationtray-behaviors-combo.svg" alt="A notification tray that has systems messages requiring user action and also a news feed item about a new user." style="margin-block-end: 0px;"/> 

- Place the most urgent or highest priority action-based messages first to ensure the most critical tasks are completed first. 
- Always include call to actions within the section including action-based messages.
- Use section titles in addition to [icons](https://design.visa.com/components/icons-illustrations) and [color](https://design.visa.com/base-elements/color) to help users scan the notifications.
- Include time stamps, either exact times or less formal options when relevant to your context.

## Behaviors
Notifications can be either passive or active depending on the importance of the message and whether action is needed. The persistence of the notification depends on the urgency of the action required. System-generated errors or actions that require users to act on them before continuing with their workflow are the most critical.

### Read vs. unread messages
Effectively distinguishing between read and unread messages is crucial for user experience. There are several methods to mark messages as read and manage unread notifications. Consider the following:
- Implement a "Mark all as read" or “Dismiss all” option for dismissing notifications.
- Action-based notifications may be marked as read after the call to action is selected or when the task has been completed.
- Activity-feed notifications may be marked as read after panel is opened, or disappear completely when “Mark as read” or “Dismiss all” is selected. Ensure this is a low effort for users and don’t require them to select each message to dismiss.

  
    #### Unread messages

    Unread messages indicate new information or tasks that require attention and have not yet been reviewed.
    <img src="https://design.visa.com/assets/components/notification-tray/input-bp-required.svg" alt="An unread notification with a blue side border and bolded text"/>
    - Use badge counters to represent unread notifications.
    - Highlight unread messages with bold text and active tab indicators to distinguish from read messages.
  
  
    #### Read messages
    
    Read messages have been acknowledged and can be referenced for historical information or follow-up actions.
    <img src="https://design.visa.com/assets/components/notification-tray/input-bp-asterisk.svg" alt="A read notification, with unbolded text and no border"/>
    - Update badge counters as users view unread messages.
    - Display read messages with standard text and no active tab indicators.
  

### Empty state
When there are no notifications, the tray will display an empty state message.
<img src="https://design.visa.com/assets/components/notification-tray/notificationtray-behaviors-empty.svg" alt="A tray with a message indicating there are no notifications."/> 

## Platform considerations
Notification trays can be accessed multiple ways in mobile. This includes the hamburger menu, top nav trailing icons, or the bottom tab bar. In mobile, notifications are viewed as a full page versus a drawer.
<img src="https://design.visa.com/assets/components/notification-tray/notificationtray-platform.svg" alt="A mobile phone screen showing a full page notifications list"/>

## Content
- Follow best practices outlined in [Messaging](https://design.visa.com/content/messaging) when writing content for individual notifications within the tray.
- Use sentence case for all content except for section labels, proper nouns, or acronyms.
- Avoid abbreviations, acronyms, or jargon unless they’re commonly understood or necessary. 

### Section label

- Don’t include punctuation.
- Use all caps with no punctuation following the overline typography pattern. 
- Indicate the purpose of the notification with clear text like “To do” or “News feed”. 
- Limit section labels to a few brief words.

### Calls to action

- Follow [Link](https://design.visa.com/components/link) and [Button](https://design.visa.com/components/button) guidelines for help crafting content for calls to action and buttons. 
- Limit link labels and buttons to a few briefs words such as “Mark as read,” “Dismiss all,” or “View all.”
- Use clear language to indicate the purpose of the link or button such as “Update now.”


---

# code

---
title: One-time passcode
description: A text field paired with CTAs enabling users to a request single-use code to authenticate a transaction or session.
meta_description: Get code for a text field paired with CTAs that enable users to request a single-use code to authenticate a transaction or session.
keywords: ["otp"]

---

## Component Code Examples: input

This component is available in the following libraries:
- **CSS** (@visa/nova-styles)
- **Flutter** (@visa/nova-flutter)
- **React** (@visa/nova-react)
- **Angular** (@visa/nova-angular)

### Instructions for AI/LLM Assistants

#### Step 1: Determine the user's preferred library

Ask the user which framework/library they're using, or infer from their project context:
- **React** - For React, Next.js, or React-based projects
- **Angular** - For Angular projects
- **Flutter** - For Flutter/Dart mobile applications
- **CSS** - For vanilla HTML/CSS or framework-agnostic styling

#### Step 2: Get available versions for the chosen library

Fetch the libraries metadata to see all available versions:

**Endpoint**: `https://design.visa.com/api/libraries.json`

**Filter by package name**:
```javascript
const response = await fetch('https://design.visa.com/api/libraries.json');
const data = await response.json();
const allLibraries = JSON.parse(data.body).data;

// Example: Get React versions
const reactVersions = allLibraries
  .filter(lib => lib.name === '@visa/nova-react')
  .map(lib => lib.version)
  .reverse(); // Latest version first

console.log(reactVersions); // ["3.0.0", "2.5.4"]

// Use reactVersions[0] for latest, or let user choose specific version
```

**Package name mappings**:
- CSS → `@visa/nova-styles`
- Flutter → `@visa/nova-flutter`
- React → `@visa/nova-react`
- Angular → `@visa/nova-angular`

#### Step 3: Fetch component data from the selected library

Build the API endpoint using the library and version:

**Endpoint Pattern**: `https://design.visa.com/api/nova-{library}-{version}.json`

**Library name mappings** (for URL):
- CSS → `styles`
- Flutter → `flutter`
- React → `react`
- Angular → `angular`

**Example (CSS 1.6.5)**:
```javascript
const libraryName = "styles"; // Determined from Step 1
const version = "1.6.5";     // Determined from Step 2
const endpoint = `https://design.visa.com/api/nova-styles-1.6.5.json`;

const response = await fetch(endpoint);
const data = await response.json();
const parsed = JSON.parse(data.body);

// Find the input component
const component = parsed.components.find(c => c.name === 'input');

// Access component data
console.log(component.description);
console.log(component.examples); // Array of code examples with snippets
console.log(component.exampleSections); // Categories of examples
```

#### Step 4: Extract the code examples

Each component has an `examples` array with code snippets:

```javascript
// Example structure:
component.examples.forEach(example => {
  console.log(example.name);           // "Default accordion"
  console.log(example.description);    // Description of the example
  console.log(example.snippets.tsx);   // TypeScript/React code
  console.log(example.snippets.dart);  // Flutter code (if Flutter library)
  console.log(example.url.github);     // Link to source code
});
```

### Quick Reference

**Component Name**: `input`

**Available in**:
- CSS: versions 1.6.5, 1.6.4, 1.6.2
- Flutter: versions 8.3.1, 8.3.0, 8.2.0, 8.1.2, 8.1.1, 8.1.0
- React: versions 3.1.0, 3.0.0, 2.5.4
- Angular: versions 7.0.0, 6.0.2, 5.1.3

**Recommended workflow**:
1. If you already know the user's library and can infer the latest version, skip directly to Step 3
2. If unsure, ask the user or fetch `/api/libraries.json` to present options
3. Build the endpoint URL and fetch the component data
4. Extract and present the relevant code examples

---

# index

---
title: One-time passcode
tab_title: Usage
description: A text field paired with CTAs enabling users to a request single-use code to authenticate a transaction or session.
meta_description: Learn how to use a text field paired with CTAs that enable users to request a single-use code to authenticate a transaction or session.
thumbnail: assets/patterns/otp-graphic.svg
keywords: ["otp", "Verification codes", "two-factor authentication (2FA) code"]
related: 
  components: 
    - input

---

One-time passcodes (OTP) are a set of random numbers generated by the system. They allow users to authenticate their account for a single transaction or session by entering their code into an [input](https://design.visa.com/components/input/usage) field.<br/><br/>
Also known as: Verification codes, two-factor authentication (2FA) code.

## Anatomy

<img src="https://design.visa.com/assets/patterns/otp/otp-anatomy.svg" alt="An input field filled with six digits with a callout A indicating the required label, callout B indicating the required input, callout C indicating the optional inline message, callout D indicating the required call to action, and callout E indicating the required resend option."/>

**A. Label (required):** Text indicating the purpose of the field.<br/>
**B. Input (required):** Text field for users to enter the one-time passcode.<br/>
**C. Inline message (optional):** Text communicating format requirements or relevant guidance.<br/>
**D. Call to action (required):** Button component enabling users to submit the code and proceed.<br/>
**E. Resend option (required):** Text and link allowing users to request a new code if needed. 

## Usage

When to use and when not to use a one time passcode

- When to use: To allow users to authenticate a single transaction or session.
- When not to use: For systems where users need continuous access and shouldn’t be interrupted by cumbersome authentication processes.

- When to use: For scenarios requiring additional security beyond a standard password authentication, such as two-factor or multi-factor authentication, account recovery, secure financial transactions, and remote access.
- When not to use: For high-risk scenarios where an OTP might not provide sufficient security.<br/><br/>For low-security scenarios or environments where the risk of unauthorized access is low.

## Best practices

- Enable the passcode to be copied from the verification method and pasted in the interface requesting the code.
- Enable auto-detection or auto-population of the passcode input field, where possible.
- Enable users to specify their preferred verification method, which is typically a phone number or email. Consider including the user’s email automatically as a verification method if it’s already associated with their account. 
- Only include numbers in the generated one-time passcode.
- Don’t use the term PIN when referring to one-time passcodes. PINs are specific to recurring identification codes for ATM transactions or debit cards. 
- Follow all best practices for [Input](https://design.visa.com/components/input/usage), [Button](https://design.visa.com/components/button/usage), and [Link](https://design.visa.com/components/link/usage) when implementing those items in the one-time passcode pattern.

## Behaviors
OTP supports several features including new code requests, a resend countdown timer, and OTP code auto-population.

### New OTP requests
When a user needs to request a new OTP, they select the “Send code” button to receive a one-time passcode. This sends a unique code to the user’s preferred verification method. Users can then enter the passcode to verify their account. 

<img src="https://design.visa.com/assets/patterns/otp/otp-behaviors-new.svg" alt="A mobile screen with an option to send a one-time passcode. A mobile screen with a message stating the code has been sent to the phone number entered."/>

- Provide clear next steps if the user enters an incorrect code, such as reminding them to re-check the code they received.

### Resend requests
Users may request a new code using the “Resend” link  if they didn’t receive the initial OTP. Users can choose to verify their identity through the same method they used the first time or choose a different method. For security reasons, limit new code requests to three attempts to prevent fraudulent users from accessing sensitive data or account credentials. 

<img src="https://design.visa.com/assets/patterns/otp/otp-behaviors-resend.svg" alt="A mobile screen with a section message stating the code has been sent to the phone number entered and a link at the bottom to send a new code. Clicking the link leads to another mobile screen with different options to receive the code: text, email, answering security questions, or signing in."/>

- Limit the number of new code requests to three attempts. 
- Ensure each generated OTP is a unique set of numbers.
- Provide clear next steps if the user has exceeded the number of allowed OTP requests, such as offering a technical support contact method.

#### Resend timer
The resend timer creates a buffer between how often users can request for their OTP to be resent. This is referred to as debouncing, and it prevents users from creating duplicate resend code requests.

<img src="https://design.visa.com/assets/patterns/otp/otp-behaviors-timer.svg" alt="A mobile screen with an OTP input field and a section message stating where the code was sent to."/>

- Remove the “Resend” link and implement a thirty-second countdown timer after the user requests a new code. 
- Enable users to request a new code after 30 seconds, if they haven’t reached their maximum number of attempts.

### Input methods
The OTP can be filled automatically or manually by the user. Automatic input, which auto-fills the OTP from a text message or app notification, is convenient and fast. Manual input, where the user types in the OTP themselves, offers more control and can be a fallback if automatic input fails.

<img src="https://design.visa.com/assets/patterns/otp/otp-behaviors-auto.svg" alt="A mobile screen with the keyboard visible below the OTP field."/>

- Display the keyboard when the OTP screen appears, reducing the need for user interaction.
- Maintain a seamless input experience if the user minimizes or switches screens by reactivating the keyboard upon return.
- Keep essential information visible when the keyboard is displayed, ensuring important content like the input field, instructions, or error messages aren’t obscured.

## Content
- Use a minimum of four digits and maximum of eight digits for the OTP. The default code is set to six digits.
- Use clear, actionable language for call-to-action labels.

### Inline message

- Limit all inline messages (including errors) to one to two short sentences with punctuation.
- Use inline messages to provide additional guidance such as format or specific syntax or values to help avoid errors.
- Provide concise, descriptive, and helpful guidance about the field's usage and necessity, avoiding technical jargon.

#### Inline error message

- Use inline error messages to draw attention to errors without causing frustration.
- Provide clear, prescriptive guidance on correcting the error. Avoid redirecting users to another page to fix it. 
- Communicate whether the problem can occur again and offer an alternative backup solution in case it does. 

## Platform considerations
OTP flows have been designed for both web and mobile platforms. Examples of each can be found in our [Task flows (internal only)](https://bookmarks.visa.com/vpds-task-flows-one-time-passcode)<!-- aria-label="task flows (internal only, opens in a new tab)" -->. 

---

# task-flows

---
title: One-time passcode
tab_title: Task flows
description: A text field paired with CTAs enabling users to a request single-use code to authenticate a transaction or session.
meta_description: Discover the steps users take to authenticate a transaction or session.
thumbnail: assets/patterns/otp-graphic.svg
tab_order: 1
keywords: ["otp"]
---

Task flows refer to the steps users progress through when interacting with patterns. They’re based on specific scenarios and demonstrate how users can successfully perform tasks within each pattern layout. To find prototypes for the task flow examples shown on this page, visit our [Task flows (internal only)](https://bookmarks.visa.com/vpds-task-flows-one-time-passcode)<!-- aria-label="task flows (internal only, opens in a new tab)" -->.

## Verification task flows
In verification flows, users are either completing the initial setup of their account information or using their verification method after setup. User success in this flow type is illustrated by the following scenarios.

### Registering verification method     

To verify their identity, the user must first set up a verification method. This initiates the verification process for their account and may follow account setup, recovery, or security settings for 2-step authentication.   

<img src="https://design.visa.com/assets/patterns/otp/otp-flows-verification-1.svg" alt="A page titled Let's set up your phone and an input field labeled Mobile phone and a button labeled send code."/>     

### Verifying identity with verification method        
              
After setting up at least one verification method, the user can initiate the flow to verify their identity. They will be prompted with a step up to verify their account or identity with an OTP.

<img src="https://design.visa.com/assets/patterns/otp/otp-flows-verification-2.svg" alt="A page titled Let's make sure it's you with a shielded phone number and a button labeled Send code."/> 

### Selecting verification method     
              
If the user has set up multiple verification methods, they can select which one they wish to use to verify their account. Verification methods may vary depending on the product.           
              
<img src="https://design.visa.com/assets/patterns/otp/otp-flows-verification-3.svg" alt="A page titled Let's make sure it's you with multiple buttons for options to send a code."/>  

## Resend task flows
In resend flows, users are requesting a new verification code to be sent to them. User success in this flow type is illustrated by the following scenarios.
<br />
30s timer countdown after Resend was initiated. Debounce when the user requests new OTP through “Resend.” Disable “Resend” after press.

### Resending code through same method     
              
The user chooses to have a new code sent through the same method they used the first time.   

<img src="https://design.visa.com/assets/patterns/otp/otp-flows-resend-1.svg" alt="A page titled Enter verification code with an input field and confirm button."/> 
                                   
### Resending code through alternate method        

The user chooses to have a new code sent through a different method.

<img src="https://design.visa.com/assets/patterns/otp/otp-flows-resend-2.svg" alt="A page titled Let's make sure it's you with multiple buttons for options to send a code."/> 

## Validation task flows
Validation flows illustrate user attempts to verify their identities and error pathways preventing success. To learn more about client-side validation and server-side validation, refer to [Forms](https://design.visa.com/patterns/forms).

### Client-side validation

         
#### Tabbing out of input field     

When tabbing out of the input field before attempting to confirm the code, the user receives feedback stating that they didn’t enter all 6 digits.   

<img src="https://design.visa.com/assets/patterns/otp/otp-flows-validation-1.svg" alt="A page titled Enter verification code with a filled input field in error state stating all six digits must be entered."/>    

#### Submitting incomplete form        

After entering an incomplete code or no code at all and attempting to submit, the user receives feedback instructing them to properly fill out the erroneous field.

<img src="https://design.visa.com/assets/patterns/otp/otp-flows-validation-2.svg" alt="A page titled Enter verification code with a filled input field in error state and error section message stating a valid code must be entered."/> 

### Server-side validation 

#### Submitting incorrect code     
              
The user submitted the incorrect code and is instructed to re-enter it correctly.   

<img src="https://design.visa.com/assets/patterns/otp/otp-flows-validation-3.svg" alt="A page titled Enter verification code with a filled input field in error state and error section message stating the code entered is incorrect."/> 

                   
#### Submitting expired code        
              
The user submits an expired code and receives feedback instructing them to request a new OTP.

<img src="https://design.visa.com/assets/patterns/otp/otp-flows-validation-4.svg" alt="A page titled Enter verification code with a filled input field in error state and error section message stating the code entered is expired."/>  

#### Maxing out code entry attempts     

The user entered the code incorrectly and reached the maximum number of attempts with the current code. They can verify their identity with a new code.   

<img src="https://design.visa.com/assets/patterns/otp/otp-flows-validation-5.svg" alt="A page titled Get new verification code with a message letting the user know they've reached the maximum number of code entry attempts and an option to send new code."/>          
            
            
#### Maxing out identity verification attempts        

The user has reached the maximum number of attempts to confirm their identity after entering mismatched data on three different codes. They can no longer confirm their identity on that device.

<img src="https://design.visa.com/assets/patterns/otp/otp-flows-validation-6.svg" alt="A page titled Identity not confirmed with a message letting the user know they were not able to confirm their identity and to contact support."/>  

---

# index

---
title: Search
tab_title: Usage
description: Input fields with technical logic to help users locate specific information in a repository or site using keywords.
meta_description: Learn how to use input fields with technical logic to help users locate specific information in a repository or site using keywords.
thumbnail: assets/patterns/search-graphic.svg
related: 
  components: 
    - button
    - input
    - progress
    - combobox
---

Search allows users to navigate through large amounts of content to find results based on the keywords entered. Search uses an [Input](https://design.visa.com/components/input/usage) field in which users can enter terms or keywords to find relevant results.

## Anatomy

<img src="https://design.visa.com/assets/patterns/search/search-anatomy.svg" alt="A search field with a callout A indicating the required leading icon, callout B indicating the required search input, and callout C indicating the required placeholder text."/>

**A. Leading icon (required):** Non-actionable icon at the beginning of the field indicating the purpose.<br/>
**B. Search input (required):** Text field enabling users to enter the requested information or data.<br/>
**C. Placeholder text (required):** Text communicating the purpose or scope of the search field.  

## Usage

When to use and when not to use different types of search

- Pattern: For global searches, or any search that will route users to a distinct results page.
- When to use: If users need real-time results or immediate feedback. Use Active search instead.

- Pattern: For small data sets, like a single page, website, or table. <br /><br /> If real-time results or constant feedback is needed and the server can handle a substantial search query load.
- When to use: For complex queries that involve multiple keywords or specific syntax. Use Basic search instead.

## Best practices

- Reference [Input](https://design.visa.com/components/input/usage) as the starting point for all search patterns. 
- Reference [Combobox](https://design.visa.com/components/combobox/usage) for additional best practices when creating search patterns using comboboxes.
- Follow [Button](https://design.visa.com/components/button/usage) guidance when implementing calls to action within search patterns. 
- Make homepage search global to allow users to navigate through all available content.
- Provide access to search from every page in an experience to ensure constant availability and ease of use.
- Maintain user’s query during result browsing to help users keep track of their search context.
- Preserve user’s query even after navigating away from the search bar to prevent loss of user input.

### Placeholder text
Search fields don't use labels because they typically use placeholder text within the search box to indicate its purpose. This approach simplifies the interface and makes it more intuitive for users. 

- Always include the search icon in the leading position. This helps users identify the search box quickly.
- If using a search button, the search icon may be omitted to simplify the design.

                    
            #### General placeholder text     

              For a global search, using general placeholder text effectively communicates the purpose of the field.   
             <img src="https://design.visa.com/assets/patterns/search/search-bp-placeholder.svg" alt="Search field with a magnifying glass icon and placeholder text stating Search."/>
             - Keep it simple and universally understood. Using "Search" as a placeholder is a widely accepted.        
          
                    
            #### Scope-specifc placeholder text  

              For more specific searches, using scope-specific placeholder text helps users understand the boundaries of their search. 
              <img src="https://design.visa.com/assets/patterns/search/search-bp-scope.svg" alt="Three search fields with placeholder texts that specify what the user is searching."/>
             - Avoid technical jargon. Use language users will recognize.
             - Keep it short. Too much text can overwhelm users.  
          

### Clear text button
Clear text buttons allow users to clear their entry from the search field. 

<img src="https://design.visa.com/assets/patterns/search/search-bp-clear-text.svg" alt="Navigation bar with an active search field showing a dropdown menu with options related to the search term 'support'."/>
- Only display the clear text button when the user is actively inputting text to prevent confusion or accidental clearing.
- Provide immediate feedback by instantly clearing the text field when the button is selected.

### Search button
When the search field is incorporated into the navigation menu, it's usually not necessary to have a separate button to start the search. This is because users typically expect the search to begin once they hit enter after typing their query. However, on specific pages dedicated to searching, like a page showing search results or an advanced search page, having a separate 'Search' button could be useful. This button can provide a clear call to action and help users, especially those less familiar with typical search conventions.

<img src="https://design.visa.com/assets/patterns/search/search-bp-button.svg" alt="Search field with a button next to it labeled Search."/>

- Ensure the search button is easy to identify using a magnifying glass icon or label.
- Use either the button or no button consistently across your experience.
- Position the search button to the right of the field. **Note:** This can depend on the design and layout of your site or application. Always consider the user flow and ease of use.

### Results shown
Regardless of whether the search is basic or active, it's essential to clearly communicate the number of results returned by a search query. This information is valuable even if the search yields zero results. 

<img src="https://design.visa.com/assets/patterns/search/search-bp-results.svg" alt="Search field with an inline message stating 849 results for 'support'."/>

- Always display the number of results. This gives the user a sense of how broad or narrow their search results are.
- Include the search query in the results message. This helps users remember what they searched for.

### Empty state
An empty state occurs when the text entered in the input field doesn't match the available options within the menu. 

<img src="https://design.visa.com/assets/patterns/search/search-bp-empty.svg" alt="Active search field with no results found."/>

- Always inform users when their search didn't match any options to avoid misinterpreting for a loading state.
- Use specific messages when possible, such as "No results found for support” to communicate that the system processed the request but didn't find any matches. This is also helpful if users are completing multiple searches.

### Progress indicators
Whenever a search requires time to load, use a [Progress](https://design.visa.com/components/progress/usage) indicator to communicate status and time to completion to the user.

<img src="https://design.visa.com/assets/patterns/search/search-bp-progress.svg" alt="Search field shown loading with a progress bar below it."/>

- Ensure the progress indicator doesn't interfere with other user activities.
- Consider providing a cancel option alongside the progress indicator for long searches.

## Layout
The search pattern has two layouts, one for basic search and another for active search. Each can be used as a starting point to enable different task flows. To learn about the search task flows and how they work with each pattern, visit the [Task flows](https://design.visa.com/patterns/search/task-flows) tab.

### Basic search
Basic search can appear at the top of a page and can be expandable or persistent. It's composed of a search input, a search icon, and an “x” UI icon button that clears the search. Optionally, it may include a "Search" or "Go" button. This layout is ideal for interfaces needing quick search access, especially when space is limited and users often search for specific items within large datasets.The simplicity of the basic search layout makes it easy for users to understand and use.

<img src="https://design.visa.com/assets/patterns/search/search-layouts-basic.svg" alt="Search field shown at the top of the page with results below it."/>

- Display search results on a results page if possible.
- Include useful information such as the number of results and the search query used. 
- Make sure that the results are easy to scan and that the most relevant results are at the top.
- Place the search input field at the top of the screen, preferably in the header for easy access.

### Active search 
Active search can appear at the top of the page or within the content area and can be expandable or persistent. It's composed of a search input, a search icon, and an “x” UI icon button that clears the search. This layout is ideal for interfaces requiring swift navigation through large datasets or applications, as it provides real-time results while users type their query. There is no "Search" or "Go" button; instead, the active search provides immediate feedback directly on the page.

<img src="https://design.visa.com/assets/patterns/search/search-layouts-active.svg" alt="Active search field shown within a navigation bar. Results are shown below as the user inputs text."/>

- Display results instantly below the search field, providing users with real-time responses to their queries. 
- Automatically navigate users to the relevant page when a result is selected. 

## Behaviors

### Expandable search 
The search icon can be used to expand a search field in the top-level navigation. The search icon is included in the navigation by default and indicates that a field can be expanded.

#### Default view

To expand the search, the user selects the icon button to expand the search field. Focus is placed on the field and users can begin to type in their query or search terms. 

<img src="https://design.visa.com/assets/patterns/search/search-behaviors-default.svg" alt="Search icon shown in horizontal navigation."/>

- Place the search icon prominently within the menu, preferably the left-most position in the top navigation.
- Always use the magnifying glass icon or search icon (like a magnifying glass) to indicate. 

#### Expanded view

After the icon is pressed, the search box expands and focus is placed on the text field, ready for users to type in their query. Essentially, this is a triggering a modal containing the search box.

<img src="https://design.visa.com/assets/patterns/search/search-behaviors-expanded.svg" alt="Search icon shown in horizontal navigation in expanded state with a search field."/>

- Ensure the search bar expands smoothly and noticeably when clicked, drawing attention to the input field.
- Make sure expanded search bar is large enough to easily enter search terms and view the full text entered.

### Persistent search
In the persistent search experience, the navigation bar contains a compact search input field that’s ready for user input.

<img src="https://design.visa.com/assets/patterns/search/search-behaviors-persistent.svg" alt="Search field shown in horizontal navigation."/>

- Place the search input in a consistent area across experiences.
- Ensure users can type at least 27 characters total into the field.

### Autosuggest 
Autosuggest, suggests options based on user input. However, it generates suggestions dynamically from a database of possible inputs, not just past entries. Autosuggest is commonly used in search fields for suggesting search terms or products. Remember, different applications handle autosuggest differently, from suggestion generation and presentation to dropdown menu interaction.
<br />
**Note:** Implementing autosuggest requires significant development effort compared to native autocomplete. Its effectiveness relies on having relevant, quickly retrievable data. Components don't include search functionality by default. If autosuggest is needed, this must be considered and implemented separately from autocomplete and may require significant and additional development effort or potentially re-architecting the application.

<img src="https://design.visa.com/assets/patterns/search/search-behaviors-autosuggest.svg" alt="Active search field with a menu of results shown."/>

- Prioritize relevance in your autosuggest results to help users reach their goal faster.
- Limit the number of autosuggest results. Aim to only include between 5 and 10 suggestions to avoid overwhelming users.
- Keep the suggestions clear and concise, making them easy to understand and select.
- Test autosuggest for consistency in function, responsiveness, result accuracy, and visual presentation across browsers.

### Discoverable results
Discoverable results are typically used in applications where the aim is to guide users towards content that they might not have thought to search for. The suggestions are generated not just from a database of possible inputs but also from an analysis of user behavior, search trends, and the overall search context.
<br />
**Note:** Implementing discoverable results requires significant development effort, similar to autosuggest. It involves not only generating suggestions based on user input but also analyzing user behavior and search trends. Components don't include search functionality by default. If discoverable results are needed, this must be considered and implemented separately from autosuggest and may require substantial development effort or potentially re-architecting the application. 

<img src="https://design.visa.com/assets/patterns/search/search-behaviors-discover.svg" alt="Active empty search field with a menu of results shown before the user has inputted any text."/>

- Understand your users by researching and comprehending their behavior, needs, and expectations. 
- Ensure that the results are relevant to the user's search intent. Avoid irrelevant suggestions.
- Limit the number of results. Aim to only include between 5 and 10 suggestions to avoid overwhelming users.
- Keep the suggestions clear and concise, making them easy to understand and select.
- Highlight the matching part of the suggestion if the user has started typing, to help users find what they're looking for.

### Filters
Filters allow users to limit their search results based on preferred attributes. They are particularly useful for global searches or when a query is likely to yield many results. 

<img src="https://design.visa.com/assets/patterns/search/search-behaviors-filters.svg" alt="List of filter options with the option to apply or clear."/>

- Implement filters after search results are returned to allow users to narrow their search.
- Ensure the filters are easy to locate, understand, and relevant to the contents of the repository.
- Communicate when a filter has been applied using a visual indicator, such as chips.
- Use [Multiselect](https://design.visa.com/components/multiselect/usage) to implement filters to allow users to apply multiple filters. 

#### Scope filters

Scope filters allow users to narrow their search to one category of information prior to entering a query. This can be a helpful way to prevent cumbersome filtering after running a query, especially if users are performing a global search with many potential results. Some common scopes include: 
- Date range: Allows users to narrow down search results within a specific time frame.
- Keyword: Allows users to search for specific words or phrases within the content.
- Category: Allows users to narrow down their search to a specific category or type of content.

<img src="https://design.visa.com/assets/patterns/search/search-behaviors-scope.svg" alt="Search field with a filter dropddown menu next to it."/>

- Always set the scope to “All” by default. 
- Ensure scope filters are intuitive and easy to understand.
- Keep the scope selection visible and easily changeable even after the search is initiated. 

## Platform considerations
Search task flows have been designed for both mobile and web platforms. 
          
<img src="https://design.visa.com/assets/patterns/search/search-platform.svg" alt="Search fields shown in mobile."/>       

## Content
- Use simple language—avoid abbreviations or jargon. 
- Use sentence case, except for proper nouns or acronyms.

### Placeholder text

- Limit placeholder text to three to five words. 
- Be consistent, if using “Search” use it consistently across your experience. If using scope-specific placeholder text keep the content short and specific to the search. Learn more in [Placeholder text](https://design.visa.com/content/placeholder-text).


---

# task-flows

---
title: Search
tab_title: Task flows
description: Input fields with technical logic to help users locate specific information in a repository or site using keywords.
meta_description: Discover the steps users take to locate specific information in a repository or site.
thumbnail: assets/patterns/search-graphic.svg
---

Task flows refer to the steps users progress through when interacting with patterns. They’re based on specific scenarios and demonstrate how users can successfully perform tasks within each pattern layout. To find prototypes for the task flow examples shown on this page, visit our [Task flows (internal only)](https://bookmarks.visa.com/vpds-task-flows-search)<!-- aria-label="task flows (internal only, opens in a new tab)" -->.

## Task flow types
There are two main search flows: basic search and active search. Additional behaviors and features may be implemented within these flows to fit your use case. These additional features are outlined in [Behaviors](https://design.visa.com/patterns/search/#behaviors).

### Basic search
Basic search, also known as search and enter, is a task flow that directs users to a distinct results page after they manually submit a query. 

<img src="https://design.visa.com/assets/patterns/search/search-layouts-basic.svg" alt="Search results page with a search field, filters and the option to sort."/>

### Active search
Active search, also known as instant or dynamic search, is a task flow that updates search results in real-time as users type their query. This eliminates the need for a separate results page or manually submitting the search. 

<img src="https://design.visa.com/assets/patterns/search/search-active.svg" alt="Active search field with Componen inputted and component related options listed below it."/>

---

# accessibility

---
title: Wizard
description: A tool that combines a wizard stepper with navigation controls to guide users through complex forms.
meta_description: Find accessibility guidelines for tools that combine a wizard stepper with navigation controls to guide users through complex forms.
thumbnail: assets/patterns/horizontal-wizard-graphic.svg
tab_order: 3
---

## Best practices

- Ensure step controls are interactive and allow users to move to the previous or next step. Use elements like `button` with descriptive `aria-labels` for current steps, completed steps, or steps that can be revisited. For unavailable steps, use non-interactive elements like `div` to prevent confusion.
- If step buttons use `aria-labels`, make sure the label dynamically updates to reflect the state of the current step. For example, the `aria-label` could be updated to “Complete step 3” or “Error step 3”. This provides screen reader users with clear and accurate information about the status of the current step.
- Place the wizard stepper in a `nav` landmark, ensuring it has a unique and descriptive `aria-label`. The label text shouldn't include the word “navigation” as this will be announced automatically and be redundant for screen readers. If the stepper doesn't allow users to navigate between steps, it doesn't need to be in a `nav` landmark.
- Add `aria-live` areas for screen readers if necessary, especially for dynamic updates like error messages or success notifications.
- Make sure icons use the library's right-to-left class for right-to-left languages.
- When users move to a new step, programmatically set focus to the first interactive element (typically the input field) in the new step. This helps keyboard and screen reader users stay oriented and interact efficiently.
 
## Keyboard controls

Keyboard actions and their corresponding behaviors for wizards

- Key: <kbd>Enter</kbd> or <kbd>Space</kbd>
- Behavior: Prompts the action associated with the focused interactive element.

- Key: <kbd>Tab</kbd>
- Behavior: Moves focus to the next focusable element.

- Key: <kbd>Shift</kbd> + <kbd>Tab</kbd>
- Behavior: Moves keyboard focus backwards to the previous interactive element.



---

# index

---
title: Wizard
description: A tool that combines a wizard stepper with navigation controls to guide users through complex forms.
meta_description: Learn how to use a wizard stepper and navigation controls to guide users through complex forms.
page_size: full-width
thumbnail: assets/patterns/wizard-graphic.svg
show_table_of_contents: false
tab_title: Code
examples:
  - slug: "multi-page"
    title: "Multi-page wizards"
  - slug: "single-page"
    title: "Single-page wizards"
  - slug: "custom"
    title: "Custom wizards"
---

<LibraryCardListLarge>
    <LibraryCardLarge 
        title="Multi-page wizards"
        description="Wizards that guide users through complex forms with multiple pages."
        href={`https://design.visa.com/patterns/wizard/multi-page`} 
        thumbnail={`https://design.visa.com/assets/patterns/wizard/horizontal-wizard-graphic.svg`}
        hasChevron
        hoverColor={colorGreen}
    />
    <LibraryCardLarge 
        title="Single-page wizards" 
        description="Wizards that guide users through simple forms on a single page."
        href={`https://design.visa.com/patterns/wizard/single-page`} 
        thumbnail={`https://design.visa.com/assets/patterns/wizard/single-page-wizard-graphic.svg`}
        hasChevron
        hoverColor={colorGreen}
    />
    <LibraryCardLarge 
        title="Custom wizards" 
        description="Wizards that display the default horizontal wizard stepper on larger screens and a compact wizard on smaller screens."
        href={`https://design.visa.com/patterns/wizard/custom`} 
        thumbnail={`https://design.visa.com/assets/patterns/wizard/compact-wizard-graphic.svg`}
        hasChevron
        hoverColor={colorGreen}
    />
</LibraryCardListLarge>


---

# task-flows

---
title: Wizard
tab_title: Task flows
description: A tool that combines navigation controls and numbered steps to guide users through complex forms.
meta_description: Discover the steps users take when navigating complex forms.
thumbnail: assets/patterns/wizard-graphic.svg
---

Task flows refer to the steps users progress through when interacting with patterns. They’re based on specific scenarios and demonstrate how users can successfully perform tasks within each pattern layout. To find prototypes for the task flow examples shown on this page, visit our [Task flows (internal only)](https://bookmarks.visa.com/vpds-task-flows-wizard)<!-- aria-label="task flows (internal only, opens in a new tab)" -->.

## Task flow types
There are two types of wizard task flows: fixed and branching. Fixed wizards have a predetermined number of steps, while branching wizards add or remove steps dynamically based on user input. Both task flows can be implemented with any of the patterns outlined in the [usage guidelines](https://design.visa.com/patterns/wizard).
<br />

**Note:** For both flow types, the multi-page example is shown using the “wizard with horizontal stepper” pattern. To create these flows with a vertical multi-page pattern, reference the [wizard with vertical stepper](https://design.visa.com/patterns/wizard/usage#wizard-with-vertical-stepper). In addition, the mobile pattern is only shown with the fixed flow, but can be implemented with branching logic as needed. 

### Fixed wizard
Fixed wizards have a predetermined structure. All users encounter the same fields regardless of their input and may return to previous steps and change their input without affecting their progression through the form.<br/>

#### Fixed wizard with multi-page pattern

<img src="https://design.visa.com/assets/patterns/wizard/wizard-flows-layouts-horizontal.svg" alt="Fixed wizard with steps labeled Employee information, Company information, and Terms and conditions with the first steps being active."/>

#### Fixed wizard with single-page pattern

<img src="https://design.visa.com/assets/patterns/wizard/wizard-flows-layouts-single.svg" alt="Fixed wizard steps shown collapsed in individual accordion like containers."/>

#### Fixed wizard mobile pattern

<img src="https://design.visa.com/assets/patterns/wizard/wizard-flows-platform-mobile.svg" alt="Fixed wizard steps shown in mobile view."/>

### Branching wizard
Branching wizards update dynamically based on the user input. As fields are completed, branching logic determines if additional fields are relevant moving forward. 
<br />

**Note:** Multi-page patterns are the preferred pattern for branching wizards, as it’s easier for users to tell when an additional step has been added. The single-page pattern is only recommended for shorter forms with minimal branching logic.<br/>

#### Branching wizard with multi-page pattern

<img src="https://design.visa.com/assets/patterns/wizard/wizard-layouts-branching-1.svg" alt="Wizard with steps labeled Employee information, Company information, and Terms and conditions with the first steps being active."/>

#### Branching wizard with single-page pattern

<img src="https://design.visa.com/assets/patterns/wizard/wizard-layouts-single-branch.svg" alt="Fixed wizard steps shown collapsed in individual accordion like containers."/>

## Feedback flows and status updates
Feedback typically occurs after the user takes an action to help them correct mistakes or guide next steps. Status refers to updates that typically don’t require user action. Both communicate important information to users such as errors and success.
<br />
Feedback and status updates can be communicated during the wizard flow, either in the middle of a step or when the user transitions between steps. 
<br />
- Reference [Forms](https://design.visa.com/patterns/forms) to learn more about form validation, as forms are a key part of a wizard flow.
- Reference [Feedback and status](https://design.visa.com/patterns/feedback-and-status) to learn more about communicating feedback and status.
- Reference [Messaging](https://design.visa.com/content/messaging) for guidance on crafting content within alert messages.

### Feedback within steps
Feedback within steps refers to error feedback that’s provided as soon as the user removes focus from a field. This can help catch simple mistakes as soon as they happen.

#### Removing focus from a field

In this flow, the user removes focus from a field, either leaving it blank or inputting data in the wrong format. Feedback should be provided immediately in the form of an error.

<img src="https://design.visa.com/assets/patterns/wizard/wizard-feedback-remove-focus.svg" alt="A screen showing a field in focus and another screen next to it showing that same field in error state."/>

- Use an inline error message to call attention to the error and help the user correct it quickly.
- Use clear language to explain the error and how to fix it. For example, ensure the message highlights if the field was left blank or provides the correct format so the user can correct it quickly.
<br/>

### Feedback between steps
Feedback between steps occurs when errors are caught as the user tries to move from one step to the next. This type of feedback calls attention to errors that weren’t caught earlier and notifies users that they can’t proceed without making corrections.  

#### Trying to proceed with errors

In this flow, the user tries to move past their current step with errors. This can happen if errors weren’t caught as soon as they occurred or if they’re more difficult to catch, such as an invalid credit card number.

<img src="https://design.visa.com/assets/patterns/wizard/wizard-feedback-errors.svg" alt="A section message within a wizard flow stating one or more fields are missing."/>

- Use inline error messages to call attention to fields with errors. 
- Use a [section message](https://design.visa.com/components/section-message/usage) to notify users that they can’t proceed past their current step without correcting errors. 
- Use clear language to tell the user what went wrong and how to fix it. 
<br/>

#### Editing previous steps in branching flows

In this flow, the user edits a previously completed step in a branching flow. Their new input affects step logic and causes an additional step to be added. 

<img src="https://design.visa.com/assets/patterns/wizard/wizard-feedback-editing-steps.svg" alt="A section message within a wizard flow stating a new step has been added based on user input."/>

- Use a [section message](https://design.visa.com/components/section-message/usage) to inform users that a step has been added as soon as branching logic determines one is necessary. This prevents confusion by calling attention to the change in the user’s workflow.  
<br/>

### Addressing network errors

In this flow, network or connectivity errors prevent submission. This can happen due to network or server failures when users try to move from one step to the next or submit the form at the end of the flow.

<img src="https://design.visa.com/assets/patterns/wizard/wizard-feedback-network.svg" alt="A banner stating lost connection."/>

- Use a [banner](https://design.visa.com/components/banner/usage) to notify users that there’s a network error preventing form submission.
<br/>

## Communicating success
Success confirmations give users confidence that they’ve successfully completed a wizard. There are two methods for communicating success: using a flag or navigating to a separate page. Whichever method you select, use it consistently across your experiences. <br/>
- Use either a success flag or a success page, not both. 
- Include calls to action when applicable, such as a tracking link or button to print responses. 
- Reference [Feedback and status](https://design.visa.com/patterns/feedback-and-status) to learn more about communicating success.
- Reference [Messaging](https://design.visa.com/content/messaging) for guidance on crafting content within success messages. 

### Success message
Success messages appear on the page that the user is directed to after exiting a wizard. Use a success flag instead of a success page when there are no follow-up actions required from the user. 

<img src="https://design.visa.com/assets/patterns/wizard/wizard-bp-success-msg.svg" alt="A flag stating success, your form has been submitted."/>

- Use a [flag](https://design.visa.com/components/flag/usage) to communicate system- or section-level success messages. 

### Success page
A success page is a landing page the user is directed to after submission. Use this method to encourage further engagement, such as visiting additional resources or starting a new task.

<img src="https://design.visa.com/assets/patterns/wizard/wizard-bp-success-page.svg" alt="A full page success message."/>

- Provide a summary within the main content area of the page to communicate what the user completed.
- Use clear calls to action to ensure users can easily navigate to the main site or relevant resources.

---

# usage

---
title: Wizard
tab_title: Usage
description: A tool that combines a wizard stepper with navigation controls to guide users through complex forms.
meta_description: Learn how to use a wizard stepper and navigation controls to guide users through complex forms.
thumbnail: assets/patterns/wizard-graphic.svg
related: 
  components: 
    - button
    - progress
  patterns:
    - forms
---

The wizard pattern combines a wizard stepper, form components, and navigation buttons to separate long forms into shorter, more manageable steps. For guidance on implementing forms, reference [Forms](https://design.visa.com/patterns/forms). <br /><br />
Also known as: Stepper, step wizard, progress wizard, progress indicator.

## Anatomy
<img src="https://design.visa.com/assets/patterns/wizard/wizard-anatomy.svg" alt="A horizontal wizard with callout A indicating the required wizard stepper, callout B indicating the required step title, callout C indicating the required content area, and callout D indicating the required calls to action."/>
**A. Wizard stepper (required):** Wizard sub-component indicating the user’s current position and remaining steps.<br /> 
**B. Step title (required):** Brief statement describing the fields contained in a step. <br /> 
**C. Content area (required):** Area containing input fields, selects, and other form components to gather input from users. <br /> 
**D. Calls to action (required):** Button components enabling users to save, exit, or proceed to the next step.

## Usage
When to use and when not to use different types of wizard

- Pattern: Multi-page
- When to use: For longer forms with four or more steps. <br /><br /> If steps are longer and contain complex fields.
- When not to use: For simpler forms with fewer than four steps. <br /><br /> If steps are short and don’t require substantial input.

- Pattern: Single-page
- When to use: For shorter forms with four or fewer steps. <br /><br /> If steps are simple or easy to complete.
- When not to use: For long forms with many steps.

- Pattern: Compact
- When to use: On mobile screens or designs with limited space.
- When not to use: On screens with sufficient space, as the compact pattern displays limited information.

## Best practices
- Use a [wizard stepper](https://design.visa.com/patterns/wizard/usage#horizontal-wizard-stepper) as the starting point for all wizard patterns.
- Follow [Forms](https://design.visa.com/patterns/forms) guidance for layout strategies when implementing forms within wizard steps.
- Reference specific component guidelines for [Select](https://design.visa.com/components/select/usage), [Input](https://design.visa.com/components/input/usage), and any other components used in steps.
- Follow [Button](https://design.visa.com/components/button/usage) guidance when implementing calls to action within wizard patterns.
- Use [tooltips](https://design.visa.com/components/tooltip/usage) or inline messages so users can access relevant information without leaving the wizard.
- Always let users edit completed steps. Reference [Branching wizard](https://design.visa.com/patterns/wizard/task-flows/#branching-wizard) for tips on handling branching logic.
- Include an indeterminate progress bar during form processing. Reference [Progress](https://design.visa.com/components/progress/usage) for more information.
- Reverse the direction of wizard elements including the stepper and buttons for right-to-left languages, as the layouts provided align with user expectations for left-to-right languages. 

### Horizontal wizard stepper
The horizontal stepper lists steps horizontally from left to right. It’s the most versatile stepper and fits most screens, but can’t accommodate extra long forms with more than six steps. It facilitates [multi-page wizard patterns](https://design.visa.com/patterns/wizard/usage#multi-page-layouts) and is used to create the wizard with horizontal stepper layout. 
- Visually differentiate the user’s current step from others by using active styling. 
- Ensure step numbers are interactive so users can select them to navigate. 

#### Scaling and reflow

Scaling and reflow refers to how content behaves as the container size changes, particularly when the container is small and can’t display all its content at once. If space is limited, step titles should wrap to the next line instead of truncating to ensure users can accurately identify each step title.

<img src="https://design.visa.com/assets/patterns/wizard/stepper-behaviors-reflow.svg" alt="A wizard with step titles wrapping to the next line."/>
- Wrap step labels to ensure they remain visible to the user as the container size changes.  
- Limit labels to two or three words so labels only wrap if it’s necessary. 

#### Animations for horizontal steppers

Steps may animate when an additional step is added. Typically, the existing steps animate by sliding outwards from the new step to make space.

<img src="https://design.visa.com/assets/patterns/wizard/stepper-behaviors-animation-horizontal.svg" alt="A wizard stepper with another step added, animated to show it taking space between what was previously the first step and second step which moves right to make space"/>
- Ensure animations are brief, subtle, and unobtrusive. 
- Implement animations consistently across steps, either animating all or none. 
- Only add steps after the user’s current step to avoid confusion and ensure they continue progressing forward.
- Reverse the animation if a step is removed. 

### Vertical wizard stepper
The vertical stepper lists steps vertically instead of horizontally and is the best choice for very long forms with more than six steps. This component facilitates multi-page wizard patterns and is used to create the wizard with vertical stepper layout. 
- Visually differentiate the user’s current step from others by using active styling. 
- Ensure step numbers are interactive so users can select them to navigate.

#### Animations for vertical steppers

Steps may animate when an additional step is added. Typically, the subsequent steps slide downward to make space for the new step.

<img src="https://design.visa.com/assets/patterns/wizard/stepper-behaviors-animation-vertical.svg" alt="A wizard stepper with another step added, animated to show it taking space between what was previously the first step and second step which moves down to make space"/>
- Ensure animations are brief, subtle, and unobtrusive. 
- Implement animations consistently across steps, either animating all or none. 
- Only add steps after the user’s current step to avoid confusion and ensure they continue progressing forward.
- Reverse the animation if a step is removed. 

### Single-page stepper
The wizard stepper is an interactive navigation element that helps users progress through wizards. The single-page stepper is used for [single-page layouts](https://design.visa.com/patterns/wizard/usage#single-page-layouts), where each step is contained in an [accordion](https://design.visa.com/components/accordion/usage).
- Visually differentiate the user's current step from others by using active styling.
- Ensure step numbers are interactive so users can select them to navigate.

#### Animations for single-page steppers

Steps may animate when opening or closing for single-page steppers. Typically, they use a smooth, vertical sliding effect. When a user selects a step header, the associated content panel expands downward, revealing the hidden content. When the user proceeds forward or back, the content panel animates upward, hiding the content.<br/><br/>
If an additional step is added to a single-page stepper, use same animations as the vertical stepper.

<img src="https://design.visa.com/assets/patterns/wizard/stepper-behaviors-animation-single.svg" alt="A step in a wizard stepper is expanded to gradually reveal content which animates downward and collapsed to gradually hide content which animates upward."/>

### Button placement
Buttons are a key element of wizards, as they enable users to save progress or navigate forward and back through steps. <br />
- Place buttons in a consistent place across steps to avoid disorienting users. 
- Reference [Button](https://design.visa.com/components/button/usage/#alignment) for additional guidance on alignment and placement.

### Form components
Wizards may include various components used in forms to collect data from users. Grouping related fields, such as address details, contact information, and payment information, reduces the cognitive load placed on users. This helps maintain user focus and prevent errors.
- Avoid including too many fields within a step. Limit steps to around five to seven simple fields or three to four complex fields. 
- Try to distribute the number of fields evenly across steps to create a balanced experience.
- Start with easier steps and progress to more complex ones to reduce the chance users will abandon the task.

### Progressive disclosure
Progressive disclosure is a method used in forms to prevent cognitive overload. Forms that use progressive disclosure show a few fields at first and reveal more as the user progresses. For example, a second address line is only shown after the user completes the first. Progressive disclosure logic is generally fixed and doesn’t depend on the user’s responses. This differs from branching logic in wizards, where user input determines what steps are relevant moving forward.
<br />
While progressive disclosure can ease cognitive load in long forms, it's not recommended for multi-step forms like wizards, as it can be redundant or confusing when combined with branching logic.
- Consider progressive disclosure when forms are moderately complex but may not require multiple steps.
- For more information on using progressive disclosure long forms reference [Forms](https://design.visa.com/patterns/forms).

### Saving progress
Users should be able to exit the wizard without losing progress. There are two methods for allowing users to save progress: autosave (recommended), and a “Save” button. These methods can be implemented together to give users extra control and confidence that their work won’t be lost. 

#### Autosave

Autosave is a feature that automatically saves changes. This prevents progress loss due to network failure or other errors. 
<img src="https://design.visa.com/assets/patterns/wizard/wizard-bp-autosave.svg" alt="A wizard with autosave implemented."/>
- Consider pairing autosave with an additional “Save” button to give users more control. 
- Place an inline message near the navigation buttons to indicate that changes have been automatically saved. 

#### "Save" button

“Save” buttons let users save progress manually. This helps users feel in control, but may result in accidental progress loss during network failures or other errors. “Save” buttons can be paired with autosave to enhance confidence and control. 
<img src="https://design.visa.com/assets/patterns/wizard/wizard-bp-savebutton.svg" alt="A dialog informs users that they have unsaved changes when they try to exit the wizard."/>
- Implement a “Save” button if your project doesn’t use autosave. 
- Use a [dialog](https://design.visa.com/components/dialog/usage) to warn users if they try to exit without saving.
- Place an inline message near the navigation buttons to indicate that changes were successfully saved. 

### Summary page
Summary pages appear as the final wizard step to allow users to review their responses before submission, reducing the likelihood of incorrect input.
<img src="https://design.visa.com/assets/patterns/wizard/wizard-bp-summary-page.svg" alt="A summary page placed at the last step in the wizard"/>
- Implement summary pages as the final step before submission.
- Ensure summary pages provide a complete overview of the user's responses from all steps.
- Provide clear controls that allow users to navigate back to edit their responses.

## Layouts 
The wizard pattern has multiple layouts to accommodate different visual designs and user needs. Each can be used as a starting point to enable different task flows. To learn about the wizard task flows and how they work with each pattern, visit the [Task flows](https://design.visa.com/patterns/wizard/task-flows) tab. 

### Multi-page layouts
#### Wizard with horizontal stepper

This layout is best for interfaces with single-column designs where the majority of content is centered. It uses a [horizontal stepper](https://design.visa.com/patterns/wizard/usage#horizontal-wizard-stepper) at the top of the pattern, above the main content area of the page. This is the preferred layout for branching flows, as the horizontal stepper makes it easiest to tell when an additional step has been added to the process.

<img src="https://design.visa.com/assets/patterns/wizard/wizard-layouts-horizontal.svg" alt="A horizontal wizard in a multi-page layout."/>
- Place the horizontal stepper at the top of the screen, above the main content area of the page. 
- Place form contents within the main content area of the page. 
- Place buttons below the form contents, aligned to the outer edges of the frame. 
- Use shorter step labels to ensure they all fit in the horizontal layout.
- Avoid horizontal steppers with more than six steps, as they can become crowded and hard to navigate.

#### Wizard with vertical stepper

This layout is best for interfaces with substantial horizontal space, as the stepper and content are organized in two columns rather than centered vertically. It uses a [vertical stepper](https://design.visa.com/patterns/wizard/usage#vertical-wizard-stepper) on the left side of the pattern, next to the main content area. 

<img src="https://design.visa.com/assets/patterns/wizard/wizard-layouts-vertical.svg" alt="A vertical wizard in a multi-page layout."/>
- Place the vertical stepper component on the left of the main content of the page. 
- Place form contents within the main content area of the page. 
- Place buttons below the form contents, aligned to the outer edges of the frame. 
- Avoid using the vertical stepper on screens with limited horizontal space, unless the form contains more than six steps.

### Single-page layouts
#### Wizard with single-page stepper

This layout provides flexibility, as it can be placed within interfaces with surrounding content. However, it's not recommended for long wizards with more than four steps. It uses a [single-page stepper](https://design.visa.com/patterns/wizard/usage#single-page-stepper), which includes collapsible content areas for every step.

<img src="https://design.visa.com/assets/patterns/wizard/wizard-layouts-single.svg" alt="A single-page wizard in a multi-page layout."/>
- Ensure steps are organized vertically. 
- Ensure only one step is expanded at a time. 
- Ensure the user’s current step automatically collapses when the user proceeds forward. 
- Place buttons below the form contents of each individual step. 

#### Chevron direction

Visually differentiate expanded and collapsed sections using the chevron direction. Only one step should be expanded at a time to streamline the experience and reduce confusion.

  
    ##### Collapsed

    Collapsed sections should use the inactive color palette.
    <img src="https://design.visa.com/assets/patterns/wizard/stepper-chevron-collapse.svg" alt="A collapsed wizard stepper in single-page layout"/>
    - Use the right pointing chevron to indicate the section expands when selected.
  
  
    ##### Expanded

    Expanded sections should use the active color palette.
    <img src="https://design.visa.com/assets/patterns/wizard/stepper-chevron-expand.svg" alt="A wizard stepper in single-page layout with the first step expanded"/>
    - Use the downward pointing chevron to indicate the section collapses when selected. 
  

## Platform considerations
The wizard pattern is available for both web and mobile platforms. Learn about screen size considerations below. 

### Mobile
The compact wizard variant may be used on mobile platforms to accommodate small screens. This variant requires less space and is placed above the content area.
<img src="https://design.visa.com/assets/patterns/wizard/wizard-platform-mobile.svg" alt="A compact wizard placed above form contents in a mobile layout."/>
- Ensure users can exit the wizard by clicking the close button.
- Always include navigation buttons, as the compact stepper isn’t interactive and can’t be used to progress forward or back.

## Content
- Use sentence case for all content except proper nouns or acronyms.
- Follow guidance in [Forms](https://design.visa.com/patterns/forms) when writing form titles, subtitles, field labels, and inline messages. 
- Reference [Button](https://design.visa.com/components/button/usage) for guidance on creating effective button labels.  
- Review [Messaging](https://design.visa.com/content/messaging) for specific guidance on how to craft content in success, warning, and error messaging.

### Step labels

- Don’t include any punctuation in step labels. 
- Limit step labels to three words or fewer. Use subtitles within steps to provide additional context.
- Ensure labels clearly and accurately summarize the fields contained in the step.



---

# index

---
title: Support
description: Get help from the experts, share knowledge, and receive updates. 
meta_description: Get help from experts, share knowledge, and stay connected.
---

## Reference our guidance
Explore the Visa Product Design System documentation first to find answers to common questions.
- Browse our [FAQs](https://design.visa.com/about-VPDS/faqs) for answers to frequent community questions.
- Understand our foundational principles including [Accessibility](https://design.visa.com/global-accessibility-requirements) and [Inclusive design](https://design.visa.com/about-VPDS/inclusive-design).
- Discover our system’s visual and architectural standards used to ensure consistent digital experiences in [Base elements](https://design.visa.com/base-elements).
- Find usage, specs, and accessibility guidance for the building blocks of the system in [Components](https://design.visa.com/components).
- Explore solutions for common interactions, from application layouts to multi-step tasks like requesting a one-time passcode in [Patterns](https://design.visa.com/patterns).
- Create insightful, inclusive, and accessible data experiences for everyone, everywhere with [Data visualization](https://design.visa.com/data-visualization).
- Discover all the essentials for writing product content like voice and tone, grammar, and alert messaging in [Content](https://design.visa.com/content).

## Join the conversation (internal only)
Visa employees can find information and get help through Microsoft Teams, office hours, regular quarterly update sessions, or by creating tickets for bugs or fixes.
- Join our [Microsoft Teams channel](https://bookmarks.visa.com/vpds-microsoft-teams-channel).
- Get design and development support, including data visualization and accessibility, during [office hours](https://bookmarks.visa.com/vpds-office-hours)<!-- aria-label="Join our office hours (internal only, opens in a new tab)" -->.
- [Create tickets](https://bookmarks.visa.com/vpds-general-create-ticket) for bugs or fixes.
- Sign up to receive [VPDS updates](https://bookmarks.visa.com/vpds-gdl)<!-- aria-label="Subscribe to our email list (internal only, opens in a new tab)" --> in your inbox.

## Stay in touch
- Email us with any questions or suggestions at [{`productdesignsystem` + `@visa.com`}](mailto:productdesignsystem@visa.com).



---

# index

---
title: "Terms of Use"
description: ""
meta_description: ""
---

Visa Product Design System Terms of Use, Version: March 19, 2025<br/><br/>

These Terms of Use ("Terms" or the “Agreement”) apply to your use or access of the Visa web site located at [design.visa.com](https://design.visa.com/) (the "Site"). The Site is the property of Visa International Service Association. BY USING OR ACCESSING THE SITE, YOU AGREE TO THIS AGREEMENT; IF YOU DO NOT AGREE, DO NOT USE OR ACCESS THIS SITE. Visa may revise this Agreement by updating this page at any time. You are bound by such revisions and should therefore visit this page, from time to time, to review the current Terms. Your continued use of the Site following the posting of changes will mean that you accept and agree to the changes. If you are accessing this Site on behalf of an organization, then the terms “you” and “your” shall refer to the organization on whose behalf you access the Site.<br/><br/>

Visa may at any time revise these Terms by updating this page. You are bound by such revisions and should therefore visit this page, from time to time, to review the current Terms.
<br/>
1. **Use** - Your use of this Site must comply with all applicable laws and regulations. Visa makes this site available to (i) to allow you access to Visa Documentation, Materials, and information about Visa Programs, and (ii) facilitate your participation in the Visa payment system or programs (collectively, the “Purpose”). You may not use this Site for any other purpose.   VISA MAY DENY ACCESS AND USE OF THE SITE AT ANY TIME FOR ANY OR NO REASON, AT VISA’S SOLE DISCRETION.
<br/>
2. **Prohibitions and Limitations** - You may only download material from this Site for internal business use and solely in connection with the Purpose. Not all material will be available for download. You must retain all copyright and other proprietary notices on downloaded and/or copied material. Without Visa’s prior written consent, you may not distribute, modify, copy, publish, transmit, display, sell, license, use, reuse or create derivative works of any of the contents of, or Material displayed on, this Site, other than in connection with the Purpose. You may not access or use this Site in any way that could, or would be intended to, damage or impair this Site, or any server or network underlying this Site, or interfere with anyone else's use and enjoyment of this Site.  You may not use the Site, Visa Documentation, or Materials for any purpose that is unlawful or prohibited by this Agreement.
<br/>
3. **Intellectual Property** - The trademarks, logos and service marks, whether registered or unregistered displayed on the Visa Site are trademarks of Visa and others. The Three Bands Design and It's Everywhere You Want To are registered trademarks of Visa in the United States and other countries (trademark denotations on the Site indicate federal registrations in the United States). Nothing contained on the Site should be construed as granting by implication, estoppel, or otherwise, any license or right to use any trademark displayed on the Visa Site without the written permission of Visa or such third party that may own the trademark. Misuse of any trademarks, or any other content, displayed on the Site is prohibited. Visa aggressively enforces its intellectual property rights, including via civil and criminal proceedings.<br/><br/>
The trademarks and copyrights not attributed to Visa are the property of their respective owners.<br/>
<br/>
4. **Open Source Software** - The Materials may contain software that is subject to terms that, as a condition of use, copying, modification or redistribution, require such software and derivative works thereof to be disclosed or distributed in source code form, to be licensed for the purpose of making derivative works, or to be redistributed free of charge (“Open Source Software”). To the extent any such license requires terms with respect to such Open Source Software that are inconsistent with this Agreement, then such rights in the applicable Open Source Software license shall take precedence over the rights granted in this Agreement, but solely with respect to such Open Source Software. You acknowledge that any applicable Open Source Software license is solely between You and the applicable licensor of the Open Source Software and that You shall comply with the applicable Open Source Software license. You agree not to use any Open Source Software in such a way that would cause any portions of the Materials to be subject to any Open Source Software licensing terms or obligations.
<br/>
5. **Submissions** - If you submit feedback or suggestions to Visa we may use your feedback or suggestions on an unrestricted basis and without obligation to you.
<br/>
6. **DISCLAIMER OF WARRANTIES AND LIMITATION OF LIABILITY** - THE SITE AND ALL MATERIAL CONTAINED THEREIN INCLUDING THE VISA DOCUMENTATION AND VISA PROGRAMS, IN WHOLE AND IN PART, ARE PROVIDED ON AN "AS IS" AND "AS AVAILABLE" BASIS, WITHOUT EXPRESS OR IMPLIED WARRANTIES OF ANY KIND, INCLUDING WARRANTIES OF TITLE, IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. WE DO NOT GUARANTEE THAT THE SITE IS VIRUS-FREE OR THAT ACCESS TO THE SITE WILL BE FREE FROM INTERRUPTIONS. TO THE FULLEST EXTENT PERMITTED UNDER APPLICABLE LAW, YOU EXPRESSLY ACKNOWLEDGE AND AGREE THAT YOU ASSUME SOLE RESPONSIBILITY AND RISK FOR YOUR USE OF THE SITE AND MATERIALS.   VISA MAKES NOT WARRANTY, REPRESENTION OR COVENANT THAT THE MATERIAL, VISA DOCUMENTATION, VISA PROGRAMS OR ANY OTHER INFORMATION DISPLAYED ON THIS SITE OR YOUR USE OF ANY OF THE FOREGOING WILL NOT INFRINGE THE RIGHTS OF ANY THIRD PARTY.<br/><br/>
IN NO EVENT AND UNDER NO CAUSE OF ACTION, INCLUDING NEGLIGENCE, SHALL VISA AND ITS AFFILIATES, AND EACH OF THEIR RESPECTIVE OFFICERS, DIRECTORS, CUSTOMERS, MEMBERS, EMPLOYEES OR AUTHORIZED AGENTS (COLLECTIVELY, THE "VISA PARTIES") BE LIABLE FOR ANY DAMAGES, CLAIMS OR LOSSES INCURRED (INCLUDING COMPENSATORY, INCIDENTAL, INDIRECT, SPECIAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES), HOWEVER CAUSED AND UNDER ANY THEORY OF LIABILITY, ARISING FROM OR IN CONNECTION WITH THE SITE, VISA DOCUMENTATION, MATERIALS, AND/OR THIS AGREEMENT, EVEN IF A VISA PARTY IS ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, CLAIMS OR LOSSES.<br/><br/>
WITHOUT LIMITING THE GENERALITY OF THE FOREGOING, THE VISA PARTIES SHALL NOT BE LIABLE TO YOU OR ANY THIRD PARTY FOR: (I) YOUR USE OF OR INABILITY TO USE THE SITE FOR ANY REASON; (II) ANY INACCURACY, INCOMPLETENESS OR MISINFORMATION CONTAINED IN ANY INFORMATION PROVIDED THROUGH THE SITE; OR (III) ANY OTHER USE BY YOU OF THE SITE, VISA DOCUMENTATION, OR MATERIALS.<br/><br/>
NOTWITHSTANDING ANYTHING TO THE CONTRARY CONTAINED HEREIN, THE VISA PARTIES' CUMULATIVE LIABILITY TO YOU ARISING FROM ANY CAUSE OF ACTION WILL AT ALL TIMES BE LIMITED TO THE LESSER OF (A) YOUR ACTUAL LOSS OR (B) ONE HUNDRED US DOLLARS (US$100)(OR EQUIVALENT IN LOCAL CURRENCY). SOME JURISDICTIONS DO NOT ALLOW THE DISCLAIMER, EXCLUSION OR LIMITATION OF CERTAIN WARRANTIES, LIABILITIES AND DAMAGES, SO SOME OF THE ABOVE DISCLAIMERS, EXCLUSIONS AND LIMITATIONS MAY NOT APPLY TO YOU. IN SUCH JURISDICTIONS, THE VISA PARTIES’ LIABILITY WILL BE LIMITED TO THE FULLEST EXTENT PERMITTED BY APPLICABLE LAW. NOTHING IN THIS AGREEMENT EXCLUDES THE VISA PARTIES’ LIABILITY FOR (A) DEATH OR PERSONAL INJURY CAUSED BY ITS NEGLIGENCE, (B) FRAUD OR FRAUDULENT MISREPRESENTATION, OR (C) ANY MATTER WHICH IT WOULD BE ILLEGAL FOR THE VISA PARTIES TO EXCLUDE OR LIMIT OR ATTEMPT TO EXCLUDE OR LIMIT LIABILITY.
<br/>
7. **Indemnification** - You are solely responsible for your use of the Site, the Visa Documentation and all Materials. You agree to indemnify, defend and hold harmless Visa, its officers, directors, employees, and the successors and assigns of the foregoing against any third party legal cause of action, claim, suit, proceeding or regulatory action brought directly against Visa or any Visa Affiliate and related losses relating to your use of the Materials, Site, Visa Documentation, and/or Visa Programs.
<br/>
8. **Links** - Visa has not reviewed all of the sites which are linked to the Site, and the fact of such links does not indicate any approval or endorsement of any material contained on any linked site. Visa is not responsible for the contents of any site linked to the Site. Your connection to and use of any such linked site is at your own risk.
<br/>
9. **Assignment** - This Agreement may not be assigned by you without the prior written consent of Visa, which consent shall not be unreasonably withheld. Notwithstanding the foregoing, consent shall not be required for assignment or transfer made: (a) by operation of law, (b) to an Affiliate, or (c) in connection with a merger, acquisition, corporate reorganization, or sale of substantially all of your assets. Except as provided in this section, any attempts by you to assign or transfer any of your rights and/or obligations under this Agreement without the prior written consent of Visa shall be null and void.
<br/>
10. **Governing Law** - This Agreement will be governed by the laws of the State of New York, USA without giving effect to its provisions regarding conflict of laws that would mandate or permit application of the substantive law of any other jurisdiction. The exclusive venue for any dispute regarding this Agreement shall be in the state courts located in New York or the federal courts located in the Southern District of New York.
<br/>
11. **Language** - The prevailing language of this Agreement is English and any dispute arising from this Agreement will be settled to the extent permitted by law based on the English version.
<br/>
12. **Entire Agreement** - This Agreement constitutes and contains the entire agreement between the Parties with respect to the subject matter hereof and supersedes any prior or contemporaneous oral or written agreements. Each party acknowledges and agrees that the other has not made any representations, warranties or agreements of any kind, except as expressly set forth herein.
<br/>
13. **Survival** - The rights and obligations of the Parties which by their nature must survive termination or expiration of this Agreement in order to achieve their fundamental purposes shall survive any termination or expiration of this Agreement, including without limitation, the provisions of this Agreement relating to intellectual property rights, disclaimers, warranties limitation of liability, indemnification, governing law, and survival.
<br/>
14. **Definitions**
        <ul>
        <li>**"Affiliate"** means, in relation to Visa, any subsidiary undertaking or parent undertaking of that person and any subsidiary undertaking of any such parent undertaking.</li>
        <li>**"Material(s)"** means all text, graphics, icons, illustrations, user interfaces, visual interfaces, images, logos, trademarks, sounds, music, artwork and computer code made available by Visa or any Visa Affiliate on this Site.</li>
        <li>**"Visa Documentation"** means collectively, the operational documents, technical integration requirements, specifications, user manual, help files, branding requirements, and other documentation made available by Visa or any Visa Affiliate on this Site.</li>
        <li>**"Visa Program"** means any program described on this Site, including, for example, the Visa Product Design System.</li>
        </ul>



---

# fy23-q3-release

---
title: "😎 Cool off with a refreshing VPDS FY24 Q3 release update"
description: "Check out newly integrated DX charts, improved design guidelines, and dark mode for an enhanced VPDS experience."
date: 2023-04-06
topics: ["dev", "release", "CSS", "flutter"]
subdirectory: "latest-news"
categories: ["release update"]
---

## Overview

Summer is sizzling, and so are these FY24 Q3 release updates. The VPDS and Data Experience (DX) teams are thrilled to announce that we’ve begun integrating DX resources into the VPDS home experience! To kick off their debut, the VPDS home experience now includes four new chart types and over 15 chart examples, all housed in a dedicated section of our site. But we're just getting warmed up! The team is gearing up to add more charts, offering a steady flow of new resources to keep you engaged throughout the summer and beyond.
<br/>
Within the new data visualization section, you can also find usage recommendations, accessibility guidelines, and code for the initial set of charts. You'll also discover enhanced design guidelines such as color palette usage, number formatting, and tips for effective chart titles—just to name a few.
<br/>
In addition, the DX team is striving to achieve tighter integration with VPDS resources. This effort will facilitate a more intuitive user experience and, like a gentle summer breeze, makes everything feel just right.
<br/>
<img src="https://design.visa.com/assets/latest-news/fy23-q3-release/july24-blog-graphic.svg" alt="Data visualization landing page"/>

## Sizzlin' code updates
The VPDS engineering team is excited to unveil the latest code updates. Adding some cool shade to your summer, we're ecstatic to announce that Nova CSS, React, Angular, and Flutter now all support dark mode! As the days get longer, you can enjoy coding into the sunset with less strain on your eyes. Just like the evening beach bonfires, we're keeping things comfortably cool and incredibly functional.

<div className="post__content_features">
<FeatureWithIcon customWidth='48' customHeight='48' style={{ color: "var(--palette-default-active)" }}>
  <svg slot="icon" width="48" height="48" viewBox="0 0 48 48" fill="none" xmlns="http://www.w3.org/2000/svg">
    <path fill-rule="evenodd" clip-rule="evenodd" d="M1 23.9938C1 27.1799 4.51044 29.9572 10.6669 31.6922C9.08557 37.8893 9.73967 42.3142 12.5 43.9067C13.2029 44.3114 14.0036 44.513 14.8129 44.4986V44.5C17.367 44.5 20.6116 42.6954 23.9978 39.3826C27.3894 42.6945 30.6338 44.4986 33.1943 44.4986C34.0022 44.5147 34.7993 44.3087 35.5 43.9053C38.2602 42.3129 38.9143 37.8897 37.3334 31.6921C43.4884 29.957 47 27.1798 47 23.9938C47 20.8076 43.4895 18.0304 37.3331 16.2953C38.9144 10.0962 38.2604 5.66471 35.5 4.07222C32.792 2.50816 28.5301 4.19318 24 8.60311C19.4699 4.19318 15.208 2.50816 12.5 4.07222C9.73963 5.66608 9.08555 10.0964 10.667 16.2954C4.5117 18.0304 1 20.8077 1 23.9938ZM26.7686 33.3009C25.898 34.4536 24.9726 35.5639 23.9957 36.6282C23.0188 35.5637 22.0933 34.4532 21.2226 33.3003C22.157 33.3457 23.0848 33.3685 24 33.3685C24.9234 33.368 25.8465 33.3454 26.7686 33.3009ZM18.7287 33.128L18.7232 33.1202C16.6398 32.9394 14.5708 32.6201 12.5302 32.1617C11.212 37.3214 11.557 41.1476 13.4588 42.2492C15.3534 43.3292 18.9098 41.6646 22.6602 38.0112C21.2458 36.4722 19.9347 34.8411 18.7356 33.1285L18.7287 33.128ZM15.8839 28.6811C16.3441 29.4787 16.8234 30.2651 17.3212 31.0394C15.8348 30.8568 14.4096 30.6142 13.0596 30.3107C13.4917 28.9323 13.9902 27.5759 14.5533 26.2462C14.9772 27.0683 15.4208 27.8802 15.8839 28.6811ZM11.1904 29.8447C11.8173 27.8495 12.5738 25.8976 13.4552 24.0015L13.4516 23.9938L13.4552 23.9861C12.5726 22.0905 11.816 20.1385 11.1904 18.1429C6.06862 19.5829 2.92481 21.7948 2.92481 23.9938C2.92481 26.1927 6.07006 28.396 11.1904 29.8447ZM13.0576 17.675C13.4909 19.0547 13.99 20.4127 14.553 21.7442C15.4018 20.0984 16.3285 18.494 17.3297 16.9366C15.895 17.1145 14.4693 17.3609 13.0576 17.675ZM24 11.3626C24.9756 12.4257 25.8997 13.5348 26.7692 14.686C24.9242 14.5968 23.0758 14.5968 21.2307 14.686C22.1003 13.5348 23.0244 12.4257 24 11.3626ZM33.4469 21.7409C32.5998 20.0966 31.6742 18.4941 30.6734 16.9388C32.1064 17.1171 33.5305 17.363 34.9408 17.6756C34.5087 19.0543 34.0101 20.411 33.4469 21.7409ZM34.5484 23.9938L34.5448 24.0014C35.4291 25.8963 36.1857 27.8485 36.8096 29.8447C41.9386 28.3974 45.0752 26.1927 45.0752 23.9938C45.0752 21.7948 41.9299 19.5916 36.8096 18.1429C36.1813 20.1375 35.4247 22.0893 34.5448 23.9861L34.5484 23.9938ZM30.6778 31.0447C31.6781 29.4918 32.6025 27.8912 33.4477 26.2484C34.0101 27.5761 34.5083 28.9303 34.9406 30.3065C33.5324 30.6223 32.1098 30.8687 30.6778 31.0447ZM29.2713 33.128L29.2655 33.1285C28.0661 34.8416 26.7546 36.4718 25.3397 38.0112C28.3269 40.9287 31.1573 42.579 33.1856 42.579H33.1928C33.7017 42.579 34.1588 42.4667 34.5412 42.2492C36.443 41.1461 36.788 37.3214 35.4698 32.1617C33.4288 32.6196 31.3594 32.9404 29.2757 33.1217L29.2713 33.128ZM14.8129 5.40858C14.2969 5.40858 13.8398 5.5137 13.4574 5.73835C11.5556 6.84142 11.2192 10.6662 12.5288 15.8259C14.5721 15.368 16.6432 15.0447 18.7287 14.8581C19.9294 13.145 21.2423 11.5137 22.6588 9.97496C19.6717 7.05743 16.8412 5.40858 14.8129 5.40858ZM29.2713 14.8581C31.3569 15.0442 33.428 15.3675 35.4712 15.8259C36.7894 10.6662 36.4444 6.83998 34.5426 5.73835C32.648 4.64392 29.0844 6.32301 25.3412 9.9764C26.7539 11.5185 28.0666 13.1495 29.2713 14.8596V14.8581ZM19.7924 31.2833C22.6229 31.5007 25.3771 31.5007 28.2147 31.2833C29.7973 28.9618 31.2038 26.5246 32.4223 23.9923C31.2089 21.4559 29.7997 19.0181 28.2076 16.7014C25.4067 16.484 22.5933 16.484 19.7924 16.7014C18.1991 19.0174 16.7899 21.4552 15.5777 23.9923C16.7966 26.5259 18.2055 28.9632 19.7924 31.2833ZM26.7916 24.001C26.7916 25.5508 25.5384 26.8011 24 26.8011C22.4615 26.8011 21.2083 25.5508 21.2083 24.001C21.2083 22.4512 22.4615 21.2008 24 21.2008C25.5384 21.2008 26.7916 22.4512 26.7916 24.001ZM28.7916 24.001C28.7916 26.652 26.6463 28.8011 24 28.8011C21.3536 28.8011 19.2083 26.652 19.2083 24.001C19.2083 21.3499 21.3536 19.2008 24 19.2008C26.6463 19.2008 28.7916 21.3499 28.7916 24.001Z" fill="currentColor"/>
  </svg>
  ### Nova React for web
  <Typography variant="body-2">In case you missed it in our last release, we now support React 19.0. In addition, Multi-select and Wizard are now available along with support for multiple themes and right-to-left languages. We're also near completion of content, design, and accessibility reviews, ensuring consistency across component libraries from design to engineering.</Typography>
  <br/>
  [Visit React changelog](https://design.visa.com/developing/react/changelog)
  [Find the package, version, and code](https://design.visa.com/developing/react) 
</FeatureWithIcon>

<FeatureWithIcon customWidth='40' customHeight='43' style={{ color: "var(--palette-default-active)" }}>
  <svg slot="icon" width="40" height="43" viewBox="0 0 40 43" fill="none" xmlns="http://www.w3.org/2000/svg">
    <path id="angular-icon" fill-rule="evenodd" clip-rule="evenodd" d="M19.6654 0L20.3428 0.243878L37.8428 6.54388L39.3308 7.07955L39.1527 8.65094L36.5 32.0509L36.3844 33.0706L35.4886 33.5714L20.6413 41.8714L19.6654 42.4169L18.6895 41.8714L3.84221 33.5714L2.94645 33.0706L2.83085 32.0509L0.178139 8.65094L0 7.07955L1.48797 6.54388L18.988 0.243878L19.6654 0ZM4.81812 31.8257L2.16541 8.42565L19.2704 2.26784L19.6654 2.12565L20.0696 2.27117L37.1654 8.42565L34.5127 31.8257L33.3342 32.4844L32.1872 33.1257L19.6654 40.1257L7.1436 33.1257L5.94479 32.4555L4.81812 31.8257ZM18.5863 17.0062L17.3018 20.1257L16.4782 22.1257H18.6411H20.7075H22.8724L22.0437 20.1257L20.7502 17.0038L19.6654 14.3857L18.5863 17.0062ZM26.4952 31.1257L24.2978 25.5657H14.9935L12.7961 31.1257H10.9042H8.71801L9.60087 29.1257L18.5703 8.80647L19.6654 6.32565L20.7555 8.80866L29.6754 29.1257L30.5534 31.1257H28.3692H26.4952Z" fill="currentColor"/>
  </svg>
  ### Nova Angular for web
  <Typography variant="body-2">Introducing Nova Angular 4.0.0! Now developers have access to Multi-select and Wizard, along with support for multiple themes and right-to-left languages. We're also near completion of content, design, and accessibility reviews, ensuring consistency across component libraries from design to engineering.</Typography> 
  <br/>
  [Visit Angular changelog](https://design.visa.com/developing/angular/changelog)
  [Find the package, version, and code](https://design.visa.com/developing/angular)
</FeatureWithIcon>

<FeatureWithIcon customWidth='44' customHeight='36' style={{ color: "var(--palette-default-active)" }}>
  <svg slot="icon"width="44" height="36" viewBox="0 0 44 36" fill="none" xmlns="http://www.w3.org/2000/svg">
    <path id="css-icon" fill-rule="evenodd" clip-rule="evenodd" d="M0 0V36H44V0H0ZM2 34V10H42V34H2ZM42 8H2V2H42V8ZM6 4H4V6H6V4ZM8 4H10V6H8V4ZM14 4H12V6H14V4ZM4 19H23V21H4V19ZM13 23H4V25H13V23ZM4 27H13V29H4V27ZM40 32H27V12H40V32ZM29 30H38V14H29V30ZM4 15H23V17H4V15Z" fill="currentColor"/>
  </svg>
  ### Nova styles for web
  <Typography variant="body-2">We're excited to announce that Multi-select and Wizard are now available, along with support for multiple themes and right-to-left languages. Annual A11y regression testing is nearing completion and we've completed content reviews across all CSS components, enhancing the consistency of libraries from Figma to CSS.</Typography> 
  <br/>
  [Visit CSS (Styles) changelog](https://design.visa.com/developing/styles-css/changelog)
  [Find the package, version, and code](https://design.visa.com/developing/styles-css)
</FeatureWithIcon>

<FeatureWithIcon customWidth='36' customHeight='40' style={{ color: "var(--palette-default-active)" }}>
  <svg slot="icon" width="36" height="40" viewBox="0 0 36 40" fill="none" xmlns="http://www.w3.org/2000/svg">
    <path id="Vector" d="M22.6543 19.4932H33.3392L23.3414 28.2441L22.4817 28.9966L23.3414 29.7491L33.3392 38.5H22.6543L11.7968 28.9966L22.6543 19.4932ZM6.88365 24.6561L1.52149 19.9972L22.6543 1.5H33.3392L6.88365 24.6561Z" stroke="currentColor" stroke-width="2"/>
  </svg>
  ### Nova Flutter for mobile
  <Typography variant="body-2">Introducing Nova Flutter 6.3.0: The VPDS accessibility team has not only completed their VGAR review of the Nova Flutter Android library, but Flutter has also been fully design reviewed.</Typography> 
  <br/>
  [Visit Flutter changelog](https://design.visa.com/developing/flutter/changelog)
  [Find the package, version, and code](https://design.visa.com/developing/flutter)
</FeatureWithIcon>
</div>

## Refreshing design updates
But those aren't the only exciting updates! By now, you might have noticed that we've added Patterns to the system. Over the past quarter, the team partnered with research to conduct a usability test on the site. We investigated our users' understanding of Patterns and whether we should reintroduce them into the system. We found that most users were able to understand and correctly navigate to Patterns to find Task flows, which are multi-step processes specific to each pattern. Now, when you visit our site, you'll discover Patterns like Wizard, OTP, and Search, each with a dedicated Task flow tab detailing these processes.

### Fictitious brands and aliases
We're deprecating the FDNB, FDCU, and FDCB fictitious brands following feedback about the dated appearance. We’ve replaced these marks with a modified lockup of our new Digital Bank branding. While teams aren't required to immediately update existing designs to the new Digital Bank mark, we encourage you to use the new placeholder brand moving forward.<br/>
<br/>
[Explore fictitious brands and user aliases (internal only)](https://bookmarks.visa.com/vpds-fictitious-brands)

### Date and time selector
We've made key updates to Date and time selector, such as transitioning to using native components. This not only simplifies the building process but also makes maintenance a breeze. Alongside this, we've thoroughly revised our guidelines to give users all the necessary information for designing effectively. These enhancements are geared towards making your experience smoother and more productive.<br/>
<br/>
[Explore date and time selector](https://design.visa.com/components/date-selector)

### File upload
We've made significant updates to File upload, now sporting a fresh redesign. Both the File uploader and File card components have been revamped for a more intuitive and user-friendly experience. File upload has also moved to patterns as part of our larger site and structural updates. And that's not all, we've also expanded our offering with additional prototype components designed specifically to create file upload flows.<br/>
<br/>
[Explore file upload](https://design.visa.com/patterns/file-upload)

<StayConnected />

---

# fy24-q4-release

---
title: "New variable modes in Figma libraries"
description: "Get the latest on new variable modes in Figma, design reviews in React, Angular, Styles, and Flutter, and enhanced pattern guidelines."
meta_description: Get the latest on new variable modes in Figma, design reviews in React, Angular, Styles, and Flutter, and enhanced pattern guidelines.
date: 2024-10-07
topics: ["dev", "release", "CSS", "flutter"]
subdirectory: "latest-news"
categories: ["release update"]
---

## Overview
As the leaves begin to turn and the air gets crisp, we're thrilled to bring you the latest updates for FY24 Q4. The VPDS team has been hard at work, and we’re excited to share some transformative updates that will enhance your design workflow this fall.
<br/>
This season, we’re making it easier than ever to move seamlessly between web and mobile platforms in Figma, all from a single library. Simply drag your component to the stage and apply the "Mobile" platform variable to see the magic happen. All mobile components are now integrated into our web components, collectively renamed "Nova: Components". As a result, we’ll be phasing out updates to the "Nova: Mobile Components" Figma library. With these variable updates, there’s no longer a need for swappable theme files, so our Visa theme file has been renamed to "Nova: Foundations".
<br/>
But that's not all! This fall, you can customize components with ease. Variable modes now let you swap typography, theme colors, shapes, and more, making your design process as smooth as a gentle autumn breeze.
<br/>
Need a preset you don't see? We’re eager to hear your thoughts on what additional presets would make these features even more useful. Your feedback is invaluable as we continue to refine and expand our offerings.
<br/>
So, grab your favorite fall beverage, and join us in exploring the new variable modes in Figma. Happy designing!
<br/>
<img src="https://design.visa.com/assets/latest-news/fy24-q4-release/september24-blog-graphic.svg" alt="UI elements shown with menus and examples for theme options"/>

## Code updates
As the seasons turn, the VPDS engineering team is excited to share the latest code updates. With improvements across React, Angular, Styles, and Flutter, you'll find your projects falling into place like autumn leaves. Stay tuned for more updates as we continue to refine and expand our offerings.

<div className="post__content_features">
<FeatureWithIcon customWidth='48' customHeight='48' style={{ color: "var(--palette-default-active)" }}>
  <svg slot="icon" width="48" height="48" viewBox="0 0 48 48" fill="none" xmlns="http://www.w3.org/2000/svg">
    <path fill-rule="evenodd" clip-rule="evenodd" d="M1 23.9938C1 27.1799 4.51044 29.9572 10.6669 31.6922C9.08557 37.8893 9.73967 42.3142 12.5 43.9067C13.2029 44.3114 14.0036 44.513 14.8129 44.4986V44.5C17.367 44.5 20.6116 42.6954 23.9978 39.3826C27.3894 42.6945 30.6338 44.4986 33.1943 44.4986C34.0022 44.5147 34.7993 44.3087 35.5 43.9053C38.2602 42.3129 38.9143 37.8897 37.3334 31.6921C43.4884 29.957 47 27.1798 47 23.9938C47 20.8076 43.4895 18.0304 37.3331 16.2953C38.9144 10.0962 38.2604 5.66471 35.5 4.07222C32.792 2.50816 28.5301 4.19318 24 8.60311C19.4699 4.19318 15.208 2.50816 12.5 4.07222C9.73963 5.66608 9.08555 10.0964 10.667 16.2954C4.5117 18.0304 1 20.8077 1 23.9938ZM26.7686 33.3009C25.898 34.4536 24.9726 35.5639 23.9957 36.6282C23.0188 35.5637 22.0933 34.4532 21.2226 33.3003C22.157 33.3457 23.0848 33.3685 24 33.3685C24.9234 33.368 25.8465 33.3454 26.7686 33.3009ZM18.7287 33.128L18.7232 33.1202C16.6398 32.9394 14.5708 32.6201 12.5302 32.1617C11.212 37.3214 11.557 41.1476 13.4588 42.2492C15.3534 43.3292 18.9098 41.6646 22.6602 38.0112C21.2458 36.4722 19.9347 34.8411 18.7356 33.1285L18.7287 33.128ZM15.8839 28.6811C16.3441 29.4787 16.8234 30.2651 17.3212 31.0394C15.8348 30.8568 14.4096 30.6142 13.0596 30.3107C13.4917 28.9323 13.9902 27.5759 14.5533 26.2462C14.9772 27.0683 15.4208 27.8802 15.8839 28.6811ZM11.1904 29.8447C11.8173 27.8495 12.5738 25.8976 13.4552 24.0015L13.4516 23.9938L13.4552 23.9861C12.5726 22.0905 11.816 20.1385 11.1904 18.1429C6.06862 19.5829 2.92481 21.7948 2.92481 23.9938C2.92481 26.1927 6.07006 28.396 11.1904 29.8447ZM13.0576 17.675C13.4909 19.0547 13.99 20.4127 14.553 21.7442C15.4018 20.0984 16.3285 18.494 17.3297 16.9366C15.895 17.1145 14.4693 17.3609 13.0576 17.675ZM24 11.3626C24.9756 12.4257 25.8997 13.5348 26.7692 14.686C24.9242 14.5968 23.0758 14.5968 21.2307 14.686C22.1003 13.5348 23.0244 12.4257 24 11.3626ZM33.4469 21.7409C32.5998 20.0966 31.6742 18.4941 30.6734 16.9388C32.1064 17.1171 33.5305 17.363 34.9408 17.6756C34.5087 19.0543 34.0101 20.411 33.4469 21.7409ZM34.5484 23.9938L34.5448 24.0014C35.4291 25.8963 36.1857 27.8485 36.8096 29.8447C41.9386 28.3974 45.0752 26.1927 45.0752 23.9938C45.0752 21.7948 41.9299 19.5916 36.8096 18.1429C36.1813 20.1375 35.4247 22.0893 34.5448 23.9861L34.5484 23.9938ZM30.6778 31.0447C31.6781 29.4918 32.6025 27.8912 33.4477 26.2484C34.0101 27.5761 34.5083 28.9303 34.9406 30.3065C33.5324 30.6223 32.1098 30.8687 30.6778 31.0447ZM29.2713 33.128L29.2655 33.1285C28.0661 34.8416 26.7546 36.4718 25.3397 38.0112C28.3269 40.9287 31.1573 42.579 33.1856 42.579H33.1928C33.7017 42.579 34.1588 42.4667 34.5412 42.2492C36.443 41.1461 36.788 37.3214 35.4698 32.1617C33.4288 32.6196 31.3594 32.9404 29.2757 33.1217L29.2713 33.128ZM14.8129 5.40858C14.2969 5.40858 13.8398 5.5137 13.4574 5.73835C11.5556 6.84142 11.2192 10.6662 12.5288 15.8259C14.5721 15.368 16.6432 15.0447 18.7287 14.8581C19.9294 13.145 21.2423 11.5137 22.6588 9.97496C19.6717 7.05743 16.8412 5.40858 14.8129 5.40858ZM29.2713 14.8581C31.3569 15.0442 33.428 15.3675 35.4712 15.8259C36.7894 10.6662 36.4444 6.83998 34.5426 5.73835C32.648 4.64392 29.0844 6.32301 25.3412 9.9764C26.7539 11.5185 28.0666 13.1495 29.2713 14.8596V14.8581ZM19.7924 31.2833C22.6229 31.5007 25.3771 31.5007 28.2147 31.2833C29.7973 28.9618 31.2038 26.5246 32.4223 23.9923C31.2089 21.4559 29.7997 19.0181 28.2076 16.7014C25.4067 16.484 22.5933 16.484 19.7924 16.7014C18.1991 19.0174 16.7899 21.4552 15.5777 23.9923C16.7966 26.5259 18.2055 28.9632 19.7924 31.2833ZM26.7916 24.001C26.7916 25.5508 25.5384 26.8011 24 26.8011C22.4615 26.8011 21.2083 25.5508 21.2083 24.001C21.2083 22.4512 22.4615 21.2008 24 21.2008C25.5384 21.2008 26.7916 22.4512 26.7916 24.001ZM28.7916 24.001C28.7916 26.652 26.6463 28.8011 24 28.8011C21.3536 28.8011 19.2083 26.652 19.2083 24.001C19.2083 21.3499 21.3536 19.2008 24 19.2008C26.6463 19.2008 28.7916 21.3499 28.7916 24.001Z" fill="currentColor"/>
  </svg>
  ### Nova React for web
  <Typography variant="body-2">We're excited to share that with React 2.2.2, the first 30 components are nearing completion and have been fully reviewed for design and accessibility. This ensures a more consistent and inclusive user experience across our library. Stay tuned for more updates as we continue to refine and expand our offerings.</Typography> 
  <br/>
  [Visit React changelog](https://design.visa.com/developing/react/changelog)
  [Find the package, version, and code](https://design.visa.com/developing/react)
</FeatureWithIcon>

<FeatureWithIcon customWidth='40' customHeight='43' style={{ color: "var(--palette-default-active)" }}>
  <svg slot="icon" width="40" height="43" viewBox="0 0 40 43" fill="none" xmlns="http://www.w3.org/2000/svg">
    <path id="angular-icon" fill-rule="evenodd" clip-rule="evenodd" d="M19.6654 0L20.3428 0.243878L37.8428 6.54388L39.3308 7.07955L39.1527 8.65094L36.5 32.0509L36.3844 33.0706L35.4886 33.5714L20.6413 41.8714L19.6654 42.4169L18.6895 41.8714L3.84221 33.5714L2.94645 33.0706L2.83085 32.0509L0.178139 8.65094L0 7.07955L1.48797 6.54388L18.988 0.243878L19.6654 0ZM4.81812 31.8257L2.16541 8.42565L19.2704 2.26784L19.6654 2.12565L20.0696 2.27117L37.1654 8.42565L34.5127 31.8257L33.3342 32.4844L32.1872 33.1257L19.6654 40.1257L7.1436 33.1257L5.94479 32.4555L4.81812 31.8257ZM18.5863 17.0062L17.3018 20.1257L16.4782 22.1257H18.6411H20.7075H22.8724L22.0437 20.1257L20.7502 17.0038L19.6654 14.3857L18.5863 17.0062ZM26.4952 31.1257L24.2978 25.5657H14.9935L12.7961 31.1257H10.9042H8.71801L9.60087 29.1257L18.5703 8.80647L19.6654 6.32565L20.7555 8.80866L29.6754 29.1257L30.5534 31.1257H28.3692H26.4952Z" fill="currentColor"/>
  </svg>
  ### Nova Angular for web
  <Typography variant="body-2">Introducing Nova Angular 4.1.2, with Angular 5.0.0 just around the corner! This update brings several accessibility and performance enhancements. We’re also thrilled to share that the first 30 components are nearly fully reviewed for design and accessibility, ensuring consistency across our libraries from design to implementation. Stay tuned for the upcoming Angular 5.0.0 release, packed with even more exciting features!</Typography> 
  <br/>
  [Visit Angular changelog](https://design.visa.com/developing/angular/changelog)
  [Find the package, version, and code](https://design.visa.com/developing/angular)
</FeatureWithIcon>

<FeatureWithIcon customWidth='44' customHeight='36' style={{ color: "var(--palette-default-active)" }}>
  <svg slot="icon"width="44" height="36" viewBox="0 0 44 36" fill="none" xmlns="http://www.w3.org/2000/svg">
    <path id="css-icon" fill-rule="evenodd" clip-rule="evenodd" d="M0 0V36H44V0H0ZM2 34V10H42V34H2ZM42 8H2V2H42V8ZM6 4H4V6H6V4ZM8 4H10V6H8V4ZM14 4H12V6H14V4ZM4 19H23V21H4V19ZM13 23H4V25H13V23ZM4 27H13V29H4V27ZM40 32H27V12H40V32ZM29 30H38V14H29V30ZM4 15H23V17H4V15Z" fill="currentColor"/>
  </svg>
  ### Nova styles for web
  <Typography variant="body-2">We're pleased to announce the latest release of our CSS library, version 1.5.2. This update introduces new component variables to support the Vault theme, providing more customization options for your projects. We've also updated the flex properties to ensure greater flexibility and responsiveness. You'll also find numerous bug fixes, resulting in improved performance and a smoother user experience.</Typography> 
  <br/>
  [Visit CSS (Styles) changelog](https://design.visa.com/developing/styles-css/changelog)
  [Find the package, version, and code](https://design.visa.com/developing/styles-css)
</FeatureWithIcon>

<FeatureWithIcon customWidth='36' customHeight='40' style={{ color: "var(--palette-default-active)" }}>
  <svg slot="icon" width="36" height="40" viewBox="0 0 36 40" fill="none" xmlns="http://www.w3.org/2000/svg">
    <path id="Vector" d="M22.6543 19.4932H33.3392L23.3414 28.2441L22.4817 28.9966L23.3414 29.7491L33.3392 38.5H22.6543L11.7968 28.9966L22.6543 19.4932ZM6.88365 24.6561L1.52149 19.9972L22.6543 1.5H33.3392L6.88365 24.6561Z" stroke="currentColor" stroke-width="2"/>
  </svg>
  ### Nova Flutter for mobile
  <Typography variant="body-2">Introducing Nova Flutter 7.3.0, a leap forward in flexibility and user experience. This release offers expanded customization options and refined component functionality. Additionally, we’ve implemented several bug fixes to enhance overall performance. Content reviews are underway, ensuring polished and consistent design.</Typography> 
  <br/>
  [Visit Flutter changelog](https://design.visa.com/developing/flutter/changelog)
  [Find the package, version, and code](https://design.visa.com/developing/flutter)
</FeatureWithIcon>
</div>

## Design updates
We're not stopping there! The VPDS team has been hard at work enhancing the patterns we offer. Be sure to check out our improved Dynamic table pattern and our brand-new Chat pattern. Comprehensive usage guidelines are available in our home experience, and Figma assets can be found in the components library.  While our engineering team is hard at work on other tasks, stay tuned in the coming quarters for information on developed examples for these assets. With the new season, we’re committed to transforming your projects with these exciting new tools.

### Chat pattern

We're excited to introduce our new Chat pattern, designed to guide you in creating seamless chat interfaces for a variety of interactions, including human-to-human, human-to-chatbot, and human-to-generative AI experiences. This comprehensive pattern offers best practices and detailed guidelines to help you design intuitive and engaging chat experiences. Whether you're building for customer service, virtual assistants, or AI-driven conversations, our new Chat pattern ensures your interfaces are both functional and user-friendly.
<br/>
[Explore Chat guidelines](https://design.visa.com/patterns/chat)

### Dynamic table

We've been diligently revising our Dynamic table experience and guidelines to bring you refined functionality, improved accessibility, and enhanced features. This update includes expandable rows and more comprehensive examples, making it easier for you to implement dynamic tables that are both powerful and intuitive.
<br/>
[Explore Dynamic table guidelines](https://design.visa.com/patterns/dynamic-table)

## What's next?
Our team remains dedicated to creating a unified, next-level experience as we prepare to take our design system public. We have some exciting changes on the way, including a new navigation experience for improved usability and tailored “Get started” content for designers and developers who are new to the system. Stay tuned for more exciting updates as we continue to refine and enhance our platform.

<StayConnected />



---

# fy25-nova-angular-6

---
title: "Meet Nova Angular 6"
description: "Deep dive into new features, updates, and performance enhancements and how we’re aligning with what the Angular team calls the “Angular renaissance”."
date: 2025-09-29
topics: ["dev", "release", "Angular"]
subdirectory: "latest-news"
categories: ["release update"]
---

<div className='news__content'>
  ## Overview 

  As part of our latest Visa Product Design System (VPDS) release, the team has upgraded Nova Angular to fully support Angular 18–20, ensuring developers can build with the latest framework features while staying aligned with Visa’s design system standards. This upgrade introduces signals-based architecture, enabling faster change detection, reactive state management, and smoother input handling. These enhancements improve performance, making easier to integrate Nova Angular into modern workflows. 
  We’ve also refined the library’s structure to enhance compatibility with other VPDS components, enabling teams to adopt Nova Angular in new projects or migrate existing ones with minimal friction.
  
  ## Strategic objectives
  
  The Nova Angular 6 upgrade was guided by three key goals:
  
  1. Empower developers with greater control over component behavior.
  2. Adopt Angular’s zoneless architecture and signals-based reactivity.
  3. Minimize breaking changes to ensure the performance and developer experience outweighed migration.
  
  This release aligns with what the Angular team calls the “Angular renaissance”—a period of rapid innovation focused on performance, developer experience, and modern architecture.
  
  ## The technical challenge
  
  We identified significant architectural areas in our implementation that could be enhanced to take advantage of the latest Angular features.
    
  1. Increase developer control
  2. Streamline state management
  3. Adopt Angular’s latest tools
  4. Move beyond Zone.js for change detection  
  
  ## Technical implementation
  
  The upgrade required significant architectural changes while maintaining compatibility where possible. We focused on four key technical areas.

  ### 1. Signal-based reactivity
  
  We migrated nearly all internal properties to Angular Signals, transforming our approach to state management. Benefits include:

  - More explicit and efficient change detection
  - Predictable execution patterns
  - Clear re-rendering logic
  - Targeted updates for improved performance
  - A single source of truth across components and directives
  
  ### 2. Dependency reduction
  
  We removed four major dependencies:
  
  - `@angular/cdk`
  - `@angular/router`
  - `rxjs`
  - `Zone.js`
  
  This reduced the library’s footprint by 40%, simplifying maintenance and improving performance.
  
  ### 3. Service modernization
  
  We replaced several services with more efficient alternatives:
  
  Nova Angular 6 service replacements

- Original service: Native HTML details/summary
- Replacement: Better accessibility, native browser support

- Original service: Partially replaced with afterNextRender from `@angular/core`
- Replacement: More efficient lifecycle management for many use cases

- Original service: PaginationControl
- Replacement: Improved flexibility and performance

- Original service: IdGenerator
- Replacement: Deterministic IDs for testing and analytics

  ### 4. Directive optimization
  
  We migrated from `@HostListener` and `@HostBinding` to the `host: {}` property. This change:
  
  - Simplified binding host properties to signals
  - Improved code organization and readability
  - Enhanced performance through more efficient binding
  - Reduced boilerplate code
  - Aligned with Angular best practices
  
  We also adopted transform functions inside inputs, allowing us to use Angular core’s default transformers and eliminate the need for coercion functions from Angular CDK library.

  ## Key changes
    
  ### Input property prioritization
  
  **Change**: User-provided inputs now take precedence over internal state.
  
  **Why**: Previously, internal defaults could override developer inputs, causing confusion. This change ensures a more predictable API and reduces support requests.

  **Example**: In the Button component, we now check for user-provided properties first before applying any internal defaults.
  
  <CodeSnippet
    isStandalone={true}
    exampleName='nova-angular-version-6-button-update-example'
    client:only="react"
    code={buttonExample}
    language="typescript"
    stickyCopyButton={false}
  />
  
  ### Deterministic IDs
  
  **Change**: Replaced random UUIDs with deterministic ID generation.
  
  **Why**: Random IDs complicated testing and analytics. Deterministic IDs improve reliability and consistency across renders.

  **Example**: The ID generator now creates predictable IDs based on component type and instance count.

  <CodeSnippet
    isStandalone={true}
    exampleName='nova-angular-nova-version-6-id-generator-example'
    client:only="react"
    code={idExample}
   language="typescript"
    stickyCopyButton={false}
  />
  
  ### Pagination control
  
  **Change**: Replaced the PaginationService with a more flexible PaginationControl.
  
  **Why**: The service-based approach was difficult to use with multiple pagination instances and required complex state management. The new control-based approach simplifies usage, improves customization, and enhances type safety.

  **Example**: The new PaginationControl provides a more declarative approach with better configuration options compared to the service-based implementation:
  
  <CodeSnippet
    isStandalone={true}
    exampleName='nova-angular-version-6-pagination-control-example'
    client:only="react"
    code={paginationExample}
   language="typescript"
    stickyCopyButton={false}
  />

  ### Nova Icons - Angular
  
  We also made key improvements to the `@visa/nova-icons-angular` package to align with the Nova Angular 6 upgrade:
  
  - Support for Angular 18, 19, and 20.
  - Reduced overall package size by ~25% (from 44.7MB to 33.5MB).
  - Reduced JavaScript footprint by ~26% (from 23.1MB to 17.5MB).
  - Improved rendering performance with signals.
  
  ## Developer experience benefits
  
  The upgrade provides several key benefits for development teams.
  
  ### Performance improvements
  
  - Reduced initial load times (15% improvement in typical applications that use Nova Angular)
  - More responsive interactions
  - Smaller bundle sizes
  
  ### Customization
  
  - Full control over component state via input signals
  - Clearer API boundaries and documentation
  
  ### Form improvements
  
  Form elements now extend Angular’s DefaultValueAccessor, fixing legacy issues and simplifying form logic.

  ### Testing efficiency
  
  - Deterministic IDs for reliable snapshot testing
  - Consistent component behavior across test runs
  - Better type safety and IDE integration
  
  ## Performance analysis
  
  The architectural changes produced significant and measurable improvements, as documented in our performance testing and bundle analysis.

  ### Testing efficiency
  
  Using the Input component as a benchmark:
  
  **Before**: 95ms average render time with Zone.js change detection
  
  **After**: 41ms average render time with Zoneless change detection (231% improvement)
  
  ### Library metrics

  Nova Angular 6 performance improvements

- Metric: 3.6MB
- Before: 1.3MB
- After: 63% reduction (2300KB)

- Metric: 621KB
- Before: 511KB
- After: 17% reduction (110KB)

- Metric: 101
- Before: 89
- After: 11% reduction

- Metric: 9
- Before: 6
- After: 33% reduction

- Metric: 10
- Before: 6
- After: 40% reduction

  These improvements translate directly to faster application startup times, reduced bundle sizes, and more responsive user interfaces.

  ## Testing strategy improvements
  
  We revamped our testing strategy to improve reliability and coverage:
  
  1. Adopted `@testing-library/angular` for rendered HTML testing.
  2. Implemented snapshot testing for component examples.
  3. Added accessibility (axe) testing.
  4. Increased test coverage from 70% to 98%
  
  These changes helped us catch edge cases earlier, reduce manual a11y reviews, and confidently make architectural improvements.
  
  ## Strategic roadmap
  
  Nova Angular 6 creates the foundation for our future component library strategy:

  - **Simplified upgrades:** Easier adoption of future Angular versions.
  - **Native-first approach:** Prioritize components that leverage native browser capabilities.
  - **Customization-focused:** Provide styles and optional controllers while allowing developers to bring their own logic.
  
  This strategic direction aligns with modern front-end practices and positions Nova Angular as a lightweight, flexible solution that enhances application development.  
</div>


---

# fy25-q2-release

---
title: "Announcing the public launch of the Visa Product Design System!"
description: "Explore updates that help streamline workflows, foster collaboration, and ensure consistency."
meta_description: Explore updates that help streamline workflows, foster collaboration, and ensure consistency.
date: 2025-04-23
topics: ["dev", "release", "CSS", "flutter"]
subdirectory: "latest-news"
categories: ["release update"]
---

## Overview
We’re thrilled to announce the public launch of the Visa Product Design System (VPDS)—your ultimate resource for creating intuitive and accessible experiences. This public release marks a major milestone, introducing comprehensive improvements designed to streamline your workflow and foster seamless collaboration.

<br/>

VPDS offers a robust suite of resources, including design guidelines, code libraries, and best practices, all aimed at delivering intuitive and inclusive experiences for everyone, everywhere. The public launch makes these resources more accessible, enabling users—including our partners—to work faster and smarter while maintaining consistency across projects.

<img className="v-mt-16" src="https://design.visa.com/assets/latest-news/fy25-q2-release/public-launch-blog-graphic.svg" alt="UI elements shown with menus and examples for theme options"/>

## What’s fresh and improved
Not only is VPDS now publicly available, but we’ve also made significant updates to the VPDS site to create a better experience for our current internal users and new external users.

<div className="post__content_features">
<FeatureWithIcon icon={VisaMapLocationCurrentHigh}>
  ### Updated left navigation
  <Typography variant="body-2">Our new left-navigation layout elevates more sections for improved wayfinding, making it easier to find what you need. This includes new, tailored sections such as “About VPDS” and “What’s new,” as well as personalized sections for “Designing” and “Developing.”</Typography> 
  <Typography variant="body-2">This new approach is rooted in VPDS user research and provides a streamlined and intuitive experience, similar to industry standards, ensuring you can quickly locate and access the resources you need.</Typography> 
</FeatureWithIcon>

<FeatureWithIcon icon={VisaCodeForkHigh}>
  ### Integrated code libraries
  <Typography variant="body-2">Our previous site linked to separate sites to access Angular, Flutter, React, and Styles (CSS) examples. Now, you can access examples for any framework in the same location using our new code library drop-downs that allow you to switch between libraries. On the new site, we’ve provided the latest versions of the coded examples. For older versions, we will still maintain separate sites and provide access to internal users.</Typography> 
  <Typography variant="body-2">Additionally, we have migrated documentation from these separate development sites to our new public page, including changelogs, to ensure essential information is centralized and easily accessible in one convenient location.</Typography> 
</FeatureWithIcon>

<FeatureWithIcon icon={VisaGuideHigh}>
  ### New educational materials
  <Typography variant="body-2">New get started guides for [designers](https://design.visa.com/designing) and [developers](https://design.visa.com/developing) mean you can quickly leverage VPDS to its full potential. This includes [Design kits](https://design.visa.com/designing/design-kits) for Figma and individual get started guides for [Angular](https://design.visa.com/developing/angular), [Flutter](https://design.visa.com/developing/flutter), [React](https://design.visa.com/developing/react), and [Styles (CSS)](https://design.visa.com/developing/styles-css).</Typography> 
  <Typography variant="body-2">Within our new About VPDS section, we’ve also added a [What is VPDS?](https://design.visa.com/about-VPDS) page and [FAQs](https://design.visa.com/about-VPDS/faqs) to make finding answers easier.</Typography> 
</FeatureWithIcon>

<FeatureWithIcon icon={VisaWriteHigh}>
  ### Streamlined terminology
  <Typography variant="body-2">Foundations (including typography, color, spacing, and more) have been renamed to [Base elements](https://design.visa.com/base-elements), aligning with our development terminology. We’ve also renamed and consolidated documentation for [Design tokens](https://design.visa.com/base-elements/design-tokens/overview), previously known as Theming, streamlining the way we facilitate standardization and customization.</Typography> 
  <Typography variant="body-2">This updated terminology fosters design-development parity by creating unified hubs for both Base elements and Design tokens, ensuring all the essential elements needed to drive consistency across experiences are easily accessible.</Typography> 
</FeatureWithIcon>

<FeatureWithIcon icon={VisaRefreshHigh}>
  ### Reorganized resources and assets
  <Typography variant="body-2">[Icons and illustrations](https://design.visa.com/components/icons-illustrations) now live under [Components](https://design.visa.com/components), while [Information architecture](https://design.visa.com/content/information-architecture) guidelines are grouped under [Content](https://design.visa.com/content), ensuring everything is right where you need it.</Typography> 
  <Typography variant="body-2">Foundational documentation such as [Inclusive design](https://design.visa.com/about-VPDS/inclusive-design) and [Accessibility guidance](https://design.visa.com/global-accessibility-requirements) have also been moved to “About VPDS,” elevating important guidance, elevating important principles and standards to ensure we all use a shared design language.</Typography> 
</FeatureWithIcon>
</div>

## Ready to get started?
<div class="v-flex v-flex-col v-gap-24">
Unlock the full potential of VPDS today. Visit the VPDS homepage to explore these updates, access resources, and experience how we’re transforming the way teams create. We also welcome our partners and those outside of Visa to learn about us and how VPDS can enhance your projects.

<p><a class="v-button v-button-secondary" href={`https://design.visa.com/`}>Get started with VPDS</a></p>
</div>

<StayConnected />



---

# fy25-q4-release

---
title: "Accelerate design and development with new patterns, library upgrades, and refreshed icons"
description: "Get the latest on new patterns—including filters, version updates across code libraries, and more."
meta_description: Get the latest on new patterns—including filters, version updates across code libraries, and more.
date: 2025-09-29
topics: ["dev", "release", "icons", "patterns"]
subdirectory: "latest-news"
categories: ["release update"]
---

## Overview
Since our [public launch in April 2025](https://design.visa.com/what's-new/latest-news/fy25-q2-release/), active users of the Visa Product Design System (VPDS) have soared to over 32,000—a clear sign of rapid adoption and growing trust across teams. Whether you’re new to VPDS or a long‑time user, our team has been moving at full speed to deliver more high‑quality assets, empowering you to build the best ways to pay and be paid.
<br/>
This release delivers brand‑new design assets for Filters and an expanded icons library—now available in [Figma](https://www.figma.com/design/hRsoQXTORzwT6S5aKwJ3GX/VPDS-Icons--Community-?node-id=89-495&p=f&t=O2Wd5JflxekXj59J-0). You’ll also find coded examples for [Application layouts](https://design.visa.com/patterns/application-layouts), [Chat](https://design.visa.com/patterns/chat), [File upload](https://design.visa.com/patterns/file-upload), and [Wizard patterns](https://design.visa.com/patterns/wizard), ready for your teams to use. On the engineering side, we’ve upgraded to React 19, Angular 20, and Flutter 3.29 with improved accessibility, along with optimized CSS styles powered by rem-based tokens.
<br/>
Dive into the rest of the updates below.

<img className="v-mt-16" src="https://design.visa.com/assets/latest-news/fy25-q4-release/q4-release-img.svg" alt="A variety of llustrated UI elements"/>

## Development updates
Check out the latest refinements and updates from our engineering and development teams. Stay tuned as we continue to refine and expand our code offerings.

<div className="post__content_features">
<FeatureWithIcon customWidth='40' customHeight='43' icon={VisaWriteHigh}>
  ### Coded pattern examples
  <Typography variant="body-2">Start coding quickly with new examples for [Application layouts](https://design.visa.com/patterns/application-layouts), [Chat](https://design.visa.com/patterns/chat), [File upload](https://design.visa.com/patterns/file-upload), and [Wizard](https://design.visa.com/patterns/wizard). Each pattern is available alongside usage and accessibility guidance, ensuring designers and developers are empowered to create consistent experiences without starting from scratch.</Typography> 
  <br/>
  [Explore all Patterns](https://design.visa.com/patterns)
</FeatureWithIcon>

<FeatureWithIcon customWidth='40' customHeight='43' style={{ color: "var(--palette-default-active)" }}>
  <svg slot="icon" width="40" height="43" viewBox="0 0 40 43" fill="none" xmlns="http://www.w3.org/2000/svg">
    <path id="angular-icon" fill-rule="evenodd" clip-rule="evenodd" d="M19.6654 0L20.3428 0.243878L37.8428 6.54388L39.3308 7.07955L39.1527 8.65094L36.5 32.0509L36.3844 33.0706L35.4886 33.5714L20.6413 41.8714L19.6654 42.4169L18.6895 41.8714L3.84221 33.5714L2.94645 33.0706L2.83085 32.0509L0.178139 8.65094L0 7.07955L1.48797 6.54388L18.988 0.243878L19.6654 0ZM4.81812 31.8257L2.16541 8.42565L19.2704 2.26784L19.6654 2.12565L20.0696 2.27117L37.1654 8.42565L34.5127 31.8257L33.3342 32.4844L32.1872 33.1257L19.6654 40.1257L7.1436 33.1257L5.94479 32.4555L4.81812 31.8257ZM18.5863 17.0062L17.3018 20.1257L16.4782 22.1257H18.6411H20.7075H22.8724L22.0437 20.1257L20.7502 17.0038L19.6654 14.3857L18.5863 17.0062ZM26.4952 31.1257L24.2978 25.5657H14.9935L12.7961 31.1257H10.9042H8.71801L9.60087 29.1257L18.5703 8.80647L19.6654 6.32565L20.7555 8.80866L29.6754 29.1257L30.5534 31.1257H28.3692H26.4952Z" fill="currentColor"/>
  </svg>
  ### Nova Angular for web
  <Typography variant="body-2">Build with the upgraded Nova Angular—now compatible with Angular 20, with support for versions 16 and 17 retired. Take advantage of more efficient change detection and reactive state management powered by Angular’s Signals. Enjoy smoother, more predictable behavior with sync issues eliminated when inputs take priority over internal state.</Typography> 
  <br/>
  [Visit Angular changelog](https://design.visa.com/developing/angular/changelog)
  [Find the package, version, and code](https://design.visa.com/developing/angular)
</FeatureWithIcon>

<FeatureWithIcon customWidth='36' customHeight='40' style={{ color: "var(--palette-default-active)" }}>
  <svg slot="icon" width="36" height="40" viewBox="0 0 36 40" fill="none" xmlns="http://www.w3.org/2000/svg">
    <path id="Vector" d="M22.6543 19.4932H33.3392L23.3414 28.2441L22.4817 28.9966L23.3414 29.7491L33.3392 38.5H22.6543L11.7968 28.9966L22.6543 19.4932ZM6.88365 24.6561L1.52149 19.9972L22.6543 1.5H33.3392L6.88365 24.6561Z" stroke="currentColor" stroke-width="2"/>
  </svg>
  ### Nova Flutter for mobile
  <Typography variant="body-2">Explore the new features in the Nova Flutter package, including a fresh SDK, improved lifecycle hygiene, and enhanced accessibility. Speed up your first-build times by up to 15% with reduced memory use and ensure VListTile selections are announced correctly in TalkBack and VoiceOver—improving WCAG 4.1.2 compliance.</Typography> 
  <br/>
  [Visit Flutter changelog](https://design.visa.com/developing/flutter/changelog)
  [Find the package, version, and code](https://design.visa.com/developing/flutter)
</FeatureWithIcon>

<FeatureWithIcon customWidth='48' customHeight='48' style={{ color: "var(--palette-default-active)" }}>
  <svg slot="icon" width="48" height="48" viewBox="0 0 48 48" fill="none" xmlns="http://www.w3.org/2000/svg">
    <path fill-rule="evenodd" clip-rule="evenodd" d="M1 23.9938C1 27.1799 4.51044 29.9572 10.6669 31.6922C9.08557 37.8893 9.73967 42.3142 12.5 43.9067C13.2029 44.3114 14.0036 44.513 14.8129 44.4986V44.5C17.367 44.5 20.6116 42.6954 23.9978 39.3826C27.3894 42.6945 30.6338 44.4986 33.1943 44.4986C34.0022 44.5147 34.7993 44.3087 35.5 43.9053C38.2602 42.3129 38.9143 37.8897 37.3334 31.6921C43.4884 29.957 47 27.1798 47 23.9938C47 20.8076 43.4895 18.0304 37.3331 16.2953C38.9144 10.0962 38.2604 5.66471 35.5 4.07222C32.792 2.50816 28.5301 4.19318 24 8.60311C19.4699 4.19318 15.208 2.50816 12.5 4.07222C9.73963 5.66608 9.08555 10.0964 10.667 16.2954C4.5117 18.0304 1 20.8077 1 23.9938ZM26.7686 33.3009C25.898 34.4536 24.9726 35.5639 23.9957 36.6282C23.0188 35.5637 22.0933 34.4532 21.2226 33.3003C22.157 33.3457 23.0848 33.3685 24 33.3685C24.9234 33.368 25.8465 33.3454 26.7686 33.3009ZM18.7287 33.128L18.7232 33.1202C16.6398 32.9394 14.5708 32.6201 12.5302 32.1617C11.212 37.3214 11.557 41.1476 13.4588 42.2492C15.3534 43.3292 18.9098 41.6646 22.6602 38.0112C21.2458 36.4722 19.9347 34.8411 18.7356 33.1285L18.7287 33.128ZM15.8839 28.6811C16.3441 29.4787 16.8234 30.2651 17.3212 31.0394C15.8348 30.8568 14.4096 30.6142 13.0596 30.3107C13.4917 28.9323 13.9902 27.5759 14.5533 26.2462C14.9772 27.0683 15.4208 27.8802 15.8839 28.6811ZM11.1904 29.8447C11.8173 27.8495 12.5738 25.8976 13.4552 24.0015L13.4516 23.9938L13.4552 23.9861C12.5726 22.0905 11.816 20.1385 11.1904 18.1429C6.06862 19.5829 2.92481 21.7948 2.92481 23.9938C2.92481 26.1927 6.07006 28.396 11.1904 29.8447ZM13.0576 17.675C13.4909 19.0547 13.99 20.4127 14.553 21.7442C15.4018 20.0984 16.3285 18.494 17.3297 16.9366C15.895 17.1145 14.4693 17.3609 13.0576 17.675ZM24 11.3626C24.9756 12.4257 25.8997 13.5348 26.7692 14.686C24.9242 14.5968 23.0758 14.5968 21.2307 14.686C22.1003 13.5348 23.0244 12.4257 24 11.3626ZM33.4469 21.7409C32.5998 20.0966 31.6742 18.4941 30.6734 16.9388C32.1064 17.1171 33.5305 17.363 34.9408 17.6756C34.5087 19.0543 34.0101 20.411 33.4469 21.7409ZM34.5484 23.9938L34.5448 24.0014C35.4291 25.8963 36.1857 27.8485 36.8096 29.8447C41.9386 28.3974 45.0752 26.1927 45.0752 23.9938C45.0752 21.7948 41.9299 19.5916 36.8096 18.1429C36.1813 20.1375 35.4247 22.0893 34.5448 23.9861L34.5484 23.9938ZM30.6778 31.0447C31.6781 29.4918 32.6025 27.8912 33.4477 26.2484C34.0101 27.5761 34.5083 28.9303 34.9406 30.3065C33.5324 30.6223 32.1098 30.8687 30.6778 31.0447ZM29.2713 33.128L29.2655 33.1285C28.0661 34.8416 26.7546 36.4718 25.3397 38.0112C28.3269 40.9287 31.1573 42.579 33.1856 42.579H33.1928C33.7017 42.579 34.1588 42.4667 34.5412 42.2492C36.443 41.1461 36.788 37.3214 35.4698 32.1617C33.4288 32.6196 31.3594 32.9404 29.2757 33.1217L29.2713 33.128ZM14.8129 5.40858C14.2969 5.40858 13.8398 5.5137 13.4574 5.73835C11.5556 6.84142 11.2192 10.6662 12.5288 15.8259C14.5721 15.368 16.6432 15.0447 18.7287 14.8581C19.9294 13.145 21.2423 11.5137 22.6588 9.97496C19.6717 7.05743 16.8412 5.40858 14.8129 5.40858ZM29.2713 14.8581C31.3569 15.0442 33.428 15.3675 35.4712 15.8259C36.7894 10.6662 36.4444 6.83998 34.5426 5.73835C32.648 4.64392 29.0844 6.32301 25.3412 9.9764C26.7539 11.5185 28.0666 13.1495 29.2713 14.8596V14.8581ZM19.7924 31.2833C22.6229 31.5007 25.3771 31.5007 28.2147 31.2833C29.7973 28.9618 31.2038 26.5246 32.4223 23.9923C31.2089 21.4559 29.7997 19.0181 28.2076 16.7014C25.4067 16.484 22.5933 16.484 19.7924 16.7014C18.1991 19.0174 16.7899 21.4552 15.5777 23.9923C16.7966 26.5259 18.2055 28.9632 19.7924 31.2833ZM26.7916 24.001C26.7916 25.5508 25.5384 26.8011 24 26.8011C22.4615 26.8011 21.2083 25.5508 21.2083 24.001C21.2083 22.4512 22.4615 21.2008 24 21.2008C25.5384 21.2008 26.7916 22.4512 26.7916 24.001ZM28.7916 24.001C28.7916 26.652 26.6463 28.8011 24 28.8011C21.3536 28.8011 19.2083 26.652 19.2083 24.001C19.2083 21.3499 21.3536 19.2008 24 19.2008C26.6463 19.2008 28.7916 21.3499 28.7916 24.001Z" fill="currentColor"/>
  </svg>
  ### Nova React for web
  <Typography variant="body-2">Discover leaner runtimes and standard kebab-case ARIA props in Nova React—now upgraded to React 19. Reduce your install size by making the @visa/nova-icons-react package optional, and remove extra forwardRef wrappers so components use the native ref prop for cleaner code and more accurate TypeScript types.</Typography> 
  <br/>
  [Visit React changelog](https://design.visa.com/developing/react/changelog)
  [Find the package, version, and code](https://design.visa.com/developing/react)
</FeatureWithIcon>

<FeatureWithIcon customWidth='44' customHeight='36' style={{ color: "var(--palette-default-active)" }}>
  <svg slot="icon" width="44" height="36" viewBox="0 0 44 36" fill="none" xmlns="http://www.w3.org/2000/svg">
    <path id="css-icon" fill-rule="evenodd" clip-rule="evenodd" d="M0 0V36H44V0H0ZM2 34V10H42V34H2ZM42 8H2V2H42V8ZM6 4H4V6H6V4ZM8 4H10V6H8V4ZM14 4H12V6H14V4ZM4 19H23V21H4V19ZM13 23H4V25H13V23ZM4 27H13V29H4V27ZM40 32H27V12H40V32ZM29 30H38V14H29V30ZM4 15H23V17H4V15Z" fill="currentColor"/>
  </svg>
  ### Nova styles for web
  <Typography variant="body-2">Experience smarter theming, fewer overrides, and better scaling with Core CSS.  Adjust dialog spacing instantly with the --v-dialog-margin token, and ensure consistent keyboard focus spacing with the dense list-item pattern. Hybrid themes now automatically follow the operating system’s light/dark setting, with consolidated light and dark styles. All sizing tokens now use rem for accurate icon and text scaling with --theme-scale-factor.</Typography> 
  <br/>
  [Visit CSS (Styles) changelog](https://design.visa.com/developing/styles-css/changelog)
  [Find the package, version, and code](https://design.visa.com/developing/styles-css)
</FeatureWithIcon>
</div>

## Design updates
Discover what’s new from our design and content design teams. Stay tuned as we continue to refine and expand our design offerings.

### Filters pattern
Accelerate your workflow with our new Filters pattern and quickly add fully responsive filtering functionality straight into your flows. Available in multiple layouts, this comprehensive pattern offers best practices and detailed guidelines to help you design intuitive and engaging experiences.
<br/>
[Explore Filters guidelines](https://design.visa.com/patterns/filters)

### Additions to the icons library
Explore our updated batch of icons for common concepts and UI actions. This release adds icons for bug, debug, goal, launch, thumbs up, thumbs down, token, and more. Browse the full collection in the [VPDS Icons library](https://www.figma.com/design/hRsoQXTORzwT6S5aKwJ3GX/VPDS-Icons--Community-?node-id=89-495&p=f&t=O2Wd5JflxekXj59J-0) 
<br/>
[Explore Icons and Illustrations guidelines](https://design.visa.com/components/icons-illustrations/usage/)

## Ready to get started?
Unlock the full potential of VPDS today. Visit the VPDS homepage to explore these updates, access resources, and experience how we’re transforming the way teams create. We also welcome our partners and those outside of Visa to learn about us and how VPDS can enhance your projects.
<br/>
<div className="v-flex v-gap-12 v-flex-wrap">
<a href={`https://design.visa.com/designing`} class="v-button v-button-secondary">Get started with VPDS</a>
</div>

<StayConnected />

---

# fy26-q2-release

---
title: "Evolve product development with expanded patterns and unified accessibility standards"
description: "Get the latest on integrated accessibility requirements, refreshed data visualization guidance, updated patterns, and more."
meta_description: Get the latest on integrated accessibility requirements, refreshed data visualization guidance, updated patterns, and more.
date: 2026-03-20
topics: ["dev", "release", "accessibility", "patterns"]
subdirectory: "latest-news"
categories: ["release update"]
---

## Overview
The Visa Product Design System (VPDS) continues to evolve with updates that strengthen our hub for designers and developers. From code library updates to a more unified accessibility experience, these improvements make it easier to build clear, consistent, and inclusive products across Visa.
<br/>
This release introduces integrated [Global accessibility requirements](https://design.visa.com/global-accessibility-requirements/) and refreshed [charts guidance](https://design.visa.com/data-visualization/design-visualization-guidelines/overview/)— making it easier than ever to find, understand, and apply the standards that shape high‑quality product experiences. Our engineering teams have also delivered a series of refinements across the Nova libraries, included expanded pattern examples, dark mode for improved usability in low‑light environments, and enhanced metadata to support agent‑assisted workflows. 
<br/>
Dive into the rest of the updates below.

<img className="v-mt-16" src="https://design.visa.com/assets/latest-news/fy26-q2-release/Blog template - 800x472.svg" alt="A variety of llustrated UI elements"/>

## Development updates
Check out the latest refinements and updates from our engineering and development teams. Explore the [Angular](https://design.visa.com/developing/angular/changelog), [Flutter](https://design.visa.com/developing/flutter/changelog), [React](https://design.visa.com/developing/react/changelog), and [Styles (CSS)](https://design.visa.com/developing/styles-css/changelog) changelogs for more information on library-specific updates. 

<div className="post__content_features">
<FeatureWithIcon customWidth='40' customHeight='43' icon={VisaWriteHigh}>
  ### Coded pattern examples
  <Typography variant="body-2">Work faster with new examples for [dynamic table](https://design.visa.com/patterns/dynamic-table), [chat](https://design.visa.com/patterns/chat), and [file upload](https://design.visa.com/patterns/file-upload), available in both Nova Angular and Nova React. Each pattern is available alongside robust usage and accessibility guidance, ensuring designers and developers are empowered to create consistent experiences.</Typography> 
  <br/>
  [Explore all Patterns](https://design.visa.com/patterns)
</FeatureWithIcon>

<FeatureWithIcon customWidth='40' customHeight='43' icon={VisaDeviceMonitorHigh}>
  ### Dark mode on VPDS
  <Typography variant="body-2">Switch seamlessly between light and dark modes in the site's top navigation. Designed for clarity in low‑light environments, this update also introduces improved color, date, and time inputs—helping you work comfortably and confidently in whichever mode you prefer.</Typography> 
</FeatureWithIcon>

<FeatureWithIcon customWidth='40' customHeight='43' icon={VisaArtificialIntelligenceHigh}>
  ### Agentic metadata updates
  <Typography variant="body-2">Experience clearer agent orientation and improved results from AI tools with enhanced metadata updates across Nova assets. These updates include copy markdown buttons on all site pages, updates to llms.txt, and additional metadata to improve agent readability.</Typography>
</FeatureWithIcon>
</div>

## Guidelines updates
Discover what’s new on the VPDS website. 

### Global accessibility requirements on VPDS
Explore Visa’s Global accessibility requirements in their new home on VPDS. Partnering closely with the Visa Accessibility team, we’ve created a more unified and discoverable accessibility hub. This integration makes it easier for designers, developers, and product teams to find and apply accessibility requirements directly within their workflows—supporting more inclusive, consistent experiences across Visa products.
<br/>
[Explore Global accessibility requirements on VPDS](https://design.visa.com/global-accessibility-requirements)

### Updated Data visualization guidelines
Dive into our refreshed chart guidance with improved clarity, accessibility, and consistency. More chart types and guidelines will be added soon—stay tuned as we continue expanding and strengthening our data visualization resources.
<br/>
[Explore Data visualization guidelines on VPDS](https://design.visa.com/data-visualization/design-visualization-guidelines/overview)

## Ready to get started?
Unlock the full potential of VPDS today. Visit the VPDS homepage to explore these updates, access resources, and experience how we’re transforming the way teams create. We also welcome our partners and those outside of Visa to learn about us and how VPDS can enhance your projects.
<br/>
<div className="v-flex v-gap-12 v-flex-wrap">
<a href={`https://design.visa.com/designing`} class="v-button v-button-secondary">Get started with VPDS</a>
</div>

<StayConnected />

---

# index

---
title: "Latest news"
description: "Get the latest announcements, news, and release updates."
meta_description: "Get the latest announcements, news, and release updates."
icon: "visa-write-high"
show_table_of_contents: false
---

<PostList />

---

# index

---
title: "Releases"
description: "Learn about the latest version of the Visa Product Design System and the release history that got us here. "
meta_description: "Learn about the latest version of the Visa Product Design System and the release history that got us here."
icon: "visa-map-directions-high"
---

<div class="non-highlighted-block">
<h2 class="v-typography-headline-2 markdown__heading">What are VPDS releases?</h2>

The Visa Product Design System team (VPDS) releases new additions and major improvements to its design and code libraries on a quarterly basis. Quarterly releases ensure VPDS maintains the highest standards of accessibility, usability, and aesthetic design. Each library is independently versioned following the [semantic versioning](https://semver.org)<!-- aria-label="semantic versioning (opens in a new tab)" --> standards. 
<br/>
Minor releases including bug fixes and patches happen continuously on an as-needed basis. 

</div>
<div class="highlighted-block">

<h2 class="v-typography-headline-2 markdown__heading" style="padding-block-start: 48px;" id="version-history">Version history</h2>

Nova is the latest version of VPDS. Complete with design kits in Figma and extensive code libraries, Nova is updated regularly to maintain the highest standards of accessibility, usability, and aesthetic design. To learn more, visit the changelogs for [CSS](https://design.visa.com/developing/styles-css/changelog), [Flutter](https://design.visa.com/developing/flutter/changelog), [React](https://design.visa.com/developing/react/changelog), [Angular](https://design.visa.com/developing/angular/changelog), or visit [Latest news](https://design.visa.com/what's-new/latest-news).

### Supported versions

Supported versions of the Visa Product Design System with descriptions, version numbers, and dates.

- Version: Major system release
- Description: August 2024
- Design release date: 1.2.1–latest
- CSS version numbers: 7.0.0–latest
- Flutter version numbers: 1.2.1–latest
- React version numbers: 3.1.1–latest

- Version: Maintenance only
- Description: August 2022
- Design release date: Not applicable
- CSS version numbers: Not applicable
- Flutter version numbers: 8.0.3–latest
- React version numbers: 10.0.0–latest

### Unsupported versions

Unsupported versions of the Visa Product Design System with descriptions, version numbers, and dates.

- Version: Major system release
- Description: August 2022
- Design release date: Below 1.2.1
- CSS version numbers: Below 7.0.0
- Flutter version numbers: Below 1.2.1
- React version numbers: Below 3.1.1

- Version: Updated brand colors and typography
- Description: April 2022
- Design release date: Not applicable
- CSS version numbers: Not applicable
- Flutter version numbers: Below 8.0.3
- React version numbers: Below 10.0.0

- Version: Minor iteration of Vault to adjust color structure
- Description: December 2020
- Design release date: Not applicable
- CSS version numbers: Not applicable
- Flutter version numbers: 4.2.0–4.4.1
- React version numbers: 3.8.1–5.0.6

- Version: Visa's first in-house design system
- Description: 2019
- Design release date: Not applicable
- CSS version numbers: Not applicable
- Flutter version numbers: 3.0.0–3.9.2
- React version numbers: 3.0.0–3.8.5

</div>
<div class="non-highlighted-block">
  <GetStarted />
</div>