); }; ``` #### Useful links - [Custom Theme Tutorial](/web/developers/tutorials/custom-themes/): This tutorial will guide you through creating a custom Abyss theme for your project. - createTheme tool : This tool allows you to create and modify themes to fit your design needs. - [Theme Provider](/web/ui/theme-provider): Provider that passes the theme object down the component tree giving your project access to Abyss tokens. - [styled Function](/web/tools/styled): Tool that allows you to create styled components. - [useToken Hook](/web/hooks/use-token): Hook that allows you to access the value of a token in your project.

Core Tokens

Below is a list of core tokens used throughout Abyss, these are split into the categories `color`, `border-radius`, `spacing`, `sizing`. _**Note:** Click on the token row to copy the token to your clipboard._

Border Radius Tokens

`border-radius` tokens are used to define the `borderRadius` on components. ```jsx const Example = styled('div', { borderRadius: '$core.border-radius.md', }); ``` ```jsx render ``` ---

Spacing Tokens

`spacing` tokens define the space between components. Generally, these are used for the `padding`, `margin`, or `gap` of components. ```jsx const Example = styled('div', { padding: '$core.spacing.50', }); ``` ```jsx render ``` ---

Sizing Tokens

`sizing` tokens define the size of components. Generally, these will be used to define the `width` or `height`. _**Note:** These tokens correspond to the default screen size breakpoints._ ```jsx const Example = styled('div', { width: '$core.sizing.300', height: '$core.sizing.300', }); ``` ```jsx render ``` ---

Color Tokens

`color` tokens are used to define the color of components. ```jsx const Example = styled('div', { backgroundColor: '$core.color.brand.100', }); ``` ```jsx render ```

Semantic Tokens

_**Note:** Click on the desired token to copy it to your clipboard._ ```jsx render ```

Brand Tokens

Brand tokens are useful for quickly defining the color of components. _**Note:** Click on the token row to copy the token to your clipboard._

Colors

Below is a list of brand tokens and their intended use cases. ```jsx const Example = styled('div', { backgroundColor: '$primary1', }); ``` ```jsx render ``` ---

Spacing

`spacing` tokens define the space between components. Generally, these will be used to define the `padding`, `margin`, or `gap` of components. ```jsx const Example = styled('div', { padding: '$md', }); ``` ```jsx render ``` ---

Accessibility

Color choices that are accessible ensure everyone can not only see every element on a page but also understand a specific, intended meaning. You want everyone to be able to see the difference between two colors right next to or on top of each other. Contrast refers to the perceived difference between foreground and background colors. People with low vision or color blindness and those with difficulty seeing the differences between colors can have trouble seeing where one element ends and another begins. As we age, the shape of our eyes changes and affects how we perceive color and how well we can distinguish color variations. If the contrast between different elements is too low, people may not be able to see them at all. Contrast is expressed as a ratio with the first number representing the foreground color and the second representing the background color. For example, 3:1 means the foreground item color is three times more intense or visible than the background value. Contrast rules apply to text as well as any content that conveys meaning, including icons, graphics, and form elements. Tools such as Colour Contrast Analyzer or WebAIM's online color contrast tool are useful for verifying contrast ratios. Color and contrast choices within a digital experience are accessible when people can: - See UI elements and content - Understand and interpret information - Take action We aim to provide a contrast ratio perceivable by all users. For this reason, UnitedHealthcare has embraced a minimum contrast ratio of 4.5:1 (foreground vs background) for UI elements and content that conveys meaning. Recommendations - Include color combinations, good contrast and poor contrast, in design documentation - Communicate meaning with more than just color, such as with color and descriptive text - Give focus indicators a unique presentation that meets contrast requirements on all backgrounds Test for a minimum contrast ratio of 4.5 to 1 for: - Non-bolded text smaller than 24 pixels (18 points) - Bold text smaller than 18 pixels (14 points) - Essential icons that are close to the body text size Test that non-text elements that communicate information meet a minimum contrast ratio of 3 to 1 for all states: - Icons - Data visualizations - Focus indicators - Controls, including their borders or boundaries - Non-bolded text at or above 24 pixels (18 points) - Bold text at or above 18 pixels (14 points) Don't worry about contrast for logos and disabled elements. Watch out for using color alone to communicate meaning. People who are color blind or blind cannot perceive the meaning by color alone. --- id: colors-v1 title: Colors category: Brand description: Colors of the Optum brand design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web?node-id=35230-117928&t=kLzKghKorCS3ltJX-0 pagination_prev: web/brand/optum/tokens pagination_next: web/brand/optum/typography-v2 customProps: { versionDefault: false } --- ## Overview Color differentiates our brands and helps create consistent experiences across our digital products. We use color to help our users know exactly what they need to focus on. We are committed to complying with the Web Content Accessibility Guidelines AA standard contrast ratios. To do this, choose primary, secondary, and extended colors that support usability by ensuring sufficient color contrast between elements. ```jsx render ``` --- ## Primary Our bold primary palette is used in logical ways throughout our products, marketing and sales to guide the eye and highlight important features. Utilizing our softer secondary colors, we bring warmth to the user experience to impart optimism and confidence. We use blue ($primary1) for primary actions, buttons, text links, for indicating progress and representing authentication. These colors are used in combination wherever a color theme may be desired. The Abyss theme can be adjusted on a case by case basis to allow for custom color components. ```jsx render Primary typography, navigation bar, button background, and component headers. This is the most common occurring blue, and should be used the most often. Used as the secondary color of our components. Primarily used for backgrounds or to contrast with $primary1. ``` --- ## Accent The accent color is used to keep things fresh and interesting. We lean on this color more frequently when brand awareness is high, or on our own properties where we control the surrounding environment. ```jsx render Use in communications, but can vary in amount from larger floods of color to small details in brand elements. ``` --- ## Interactive Our interactive palette contains a variety of colors make every moment feel on-brand and every interaction informative. Each color is selected intentionally to provide meaningful feedback within our products. ```jsx render Use for elements the user can interact with such as links or icons. Use when implementing hover for an $interactive1 element. Use when implementing hover for a secondary button. ``` --- ### Tint Tints are reserved for containing boxes to highlight information. Tints are used for background fills, visual sectioning, and callouts. They appear behind scrollable content to add visual sectioning and accents. ```jsx render Use in background colors for layouts, illustrations, product and portraiture photography. Use in background colors for layouts, illustrations, product and portraiture photography. ``` --- ## Data visualization Our Data Viz color palette contains a variety of colors with different categories. ### Primary palette Data Viz primary color palette. ```jsx render Use for data viz background and border. Use when implementing lighter background. ``` --- ### Secondary palette Data Viz secondary color palette. ```jsx render <> Use for data viz background and border. Use when implementing lighter background. Use for data viz background and border. Use when implementing lighter background. Use for data viz background and border. Use when implementing lighter background. Use for data viz background and border. Use when implementing lighter background. ``` --- ### Secondary status Data Viz status color palette. ```jsx render <> Use for data viz background and border status of graph. Use when implementing lighter background. Use for data viz background and border status of graph. Use when implementing lighter background. ``` --- ## Supporting Supporting colors are primarily used for infographics and data visualizations. ```jsx render Use in digital spaces, for infographic and data visualizations. Use in digital spaces, for infographic and data visualizations. Use in digital spaces, for infographic and data visualizations. Use in digital spaces, for infographic and data visualizations. Use in digital spaces, for infographic and data visualizations. Use in digital spaces, for infographic and data visualizations. ``` ### Status ```jsx render Use to indicate success to the user such as upon completion of a form. Use for a hover or unfocused version of success. Use to indicate an error to the user such as when a form submission fails. Use for a hover or unfocused version of error. Use to indicate a warning to the user such as when a form submission goes through but may be inaccurate. Use for a hover or unfocused version of warning. Use to indicate information to the user such as after a form is submitted and important information needs to be conveyed. Use for a hover or unfocused version of info. ``` ### Neutrals Neutrals have varying degrees of saturation that allow for the appropriate level of warmth across marketing and product. Typically they are used for text and subtle backgrounds when we don't want to draw too much attention to a particular touchpoint or convey information such as "disabled". Gray tints are limited to print when black is the only color option. ```jsx render Use White as a background or to contrast with darker colors. Implement white where it will never be necessary for the color theme to change. Use as a background color for delineation in Layouts. Use as a background color for delineation in Layouts. Use as a background color for delineation in Layouts. Use for additional delineation in Layouts. Use for disabled text only. Use for paragraph text. Use for labels and borders. When used on white background it may be used for legal copy. Use for headings h4-h6, body text and dark accents such as outlines, and actions. Use for headings, body text and dark accents such as outlines, and actions. Use for headings, body text and dark accents such as outlines, and actions. ``` --- ## Accessibility Color choices that are accessible ensure everyone can not only see every element on a page, but also understand a specific, intended meaning. You want everyone to be able to see the difference between two colors right next to or on top of each other. Contrast refers to the perceived difference between foreground and background colors. People with low vision or color blindness, and those who have difficulty seeing the differences between colors all can have trouble seeing where one element ends and another begins. As we age, the shape of our eyes changes and that affects both how we perceive color and how well we can distinguish variations in color. If the contrast between different elements is too low, people may not be able to see them at all. Contrast is expressed as a ratio with the first number representing the foreground color and the second representing the background color. For example, 3:1 means the foreground item color is three times more intense or visible than the background value. Contrast rules apply to text as well as any content that conveys meaning, including icons, graphics and form elements. Tools such as Colour Contrast Analyser or WebAIM's online color contrast tool are useful for verifying contrast ratios. Color and contrast choices within a digital experience are accessible when people can: - See UI elements and content - Understand and interpret information - Take action Our aim is to provide a contrast ratio that can be perceived by all users. For this reason, UnitedHealthcare has embraced a minimum contrast ratio of 4.5:1 (foreground vs background) for UI elements and content that convey meaning. Recommendations - Include color combinations, good contrast and poor contrast, in design documentation - Communicate meaning with more than just color, such as with color and descriptive text - Give focus indicators a unique presentation that meets contrast requirements on all backgrounds Test for a minimum contrast ratio 4.5 to 1 for: - Non-bolded text smaller than 24 pixels (18 points) - Bold text smaller than 18 pixels (14 points) - Essential icons that are close to body text size Test that non-text elements that communicate information meet a minimum contrast ratio of 3 to 1 for all states: - Icons - Data visualizations - Focus indicators - Controls, including their borders or boundaries - Non-bolded text at or above 24 pixels (18 points) - Bold text at or above 18 pixels (14 points) in size Don't worry about contrast for logos and disabled elements. Watch out for using color alone to communicate meaning. People who are color blind or blind cannot perceive the meaning by color alone. Useful Resources for Color Accessibility - Color and contrast accessibility - Accessibility testing for color contrast --- id: colors-v2 title: Colors category: Brand description: Colors of the Optum brand design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=1-16&node-type=canvas&t=9Oze02yWZcioUONN-0 pagination_prev: web/brand/optum/tokens pagination_next: web/brand/optum/typography-v2 customProps: { versionDefault: true } --- ## Overview Color differentiates our brands and helps create consistent experiences across our digital products. We use color to help our users know exactly what they need to focus on. We are committed to complying with the Web Content Accessibility Guidelines AA standard contrast ratios. To do this, choose primary, secondary, and extended colors that support usability by ensuring sufficient color contrast between elements. ```jsx render ``` --- ## Brand Primary colors communicate brand identity, widely used across interactive elements and is sparingly used for text - cta labels and headings. ```jsx render ``` --- ## Neutral Use neutrals for text, borders and backgrounds. ```jsx render ``` --- ## Semantic Communicates status and urgency. Use saturated colors for both text and high emphasis backgrounds. Use tint variations for backgrounds only. ```jsx render ``` --- ## Accent Use for emphasis and to communicate function. Does not have hierarchy. ```jsx render ``` ## Data visualization Used in our Data Visualization components. ```jsx render ``` --- ## Accessibility Color choices that are accessible ensure everyone can not only see every element on a page, but also understand a specific, intended meaning. You want everyone to be able to see the difference between two colors right next to or on top of each other. Contrast refers to the perceived difference between foreground and background colors. People with low vision or color blindness, and those who have difficulty seeing the differences between colors all can have trouble seeing where one element ends and another begins. As we age, the shape of our eyes changes and that affects both how we perceive color and how well we can distinguish variations in color. If the contrast between different elements is too low, people may not be able to see them at all. Contrast is expressed as a ratio with the first number representing the foreground color and the second representing the background color. For example, 3:1 means the foreground item color is three times more intense or visible than the background value. Contrast rules apply to text as well as any content that conveys meaning, including icons, graphics and form elements. Tools such as Colour Contrast Analyser or WebAIM's online color contrast tool are useful for verifying contrast ratios. Color and contrast choices within a digital experience are accessible when people can: - See UI elements and content - Understand and interpret information - Take action Our aim is to provide a contrast ratio that can be perceived by all users. For this reason, UnitedHealthcare has embraced a minimum contrast ratio of 4.5:1 (foreground vs background) for UI elements and content that convey meaning. Recommendations - Include color combinations, good contrast and poor contrast, in design documentation - Communicate meaning with more than just color, such as with color and descriptive text - Give focus indicators a unique presentation that meets contrast requirements on all backgrounds Test for a minimum contrast ratio 4.5 to 1 for: - Non-bolded text smaller than 24 pixels (18 points) - Bold text smaller than 18 pixels (14 points) - Essential icons that are close to body text size Test that non-text elements that communicate information meet a minimum contrast ratio of 3 to 1 for all states: - Icons - Data visualizations - Focus indicators - Controls, including their borders or boundaries - Non-bolded text at or above 24 pixels (18 points) - Bold text at or above 18 pixels (14 points) in size Don't worry about contrast for logos and disabled elements. Watch out for using color alone to communicate meaning. People who are color blind or blind cannot perceive the meaning by color alone. Useful Resources for Color Accessibility - Color and contrast accessibility - Accessibility testing for color contrast --- id: get-started category: Brand title: Brand description: Abyss partners closely with the Optum Brand and Design Standards to create a unified brand experience in the digital world. hideHeaderActions: true isHidden: true --- ## Latest updates ## Brand assets --- id: typography-v1 title: Typography category: Brand description: Typography for Optum brands pagination_prev: web/brand/optum/colors-v2 pagination_next: web/brand/optum/icon-brand customProps: { versionDefault: false } --- ## Overview Typography is the art and technique of arranging type to make written language legible. In the Abyss library, [Heading](/web/ui/heading) and [Text](/web/ui/text) dive into the detail behind text formatting for Optum branding. More in depth guidance on typography can be found below and in the Optum Brand Page. ```jsx render ``` --- ## Headings Headings identify chunks of related content on a page and establish the hierarchy showing how those chunks of content relate to each other. If someone reads only the headings on a page, they will get a general understanding of the information presented. HTML defines six heading levels: H1 to H6. H1 identifies an entire page, or overall topic, and is the most important level. There should only be 1 H1 per page. Find further documentation in the [Heading](/web/ui/heading) component. **Note**: The term "Abyss" prefixes fonts such as "Enterprise Sans VF" in the documentation under Font Family. This is because from a code perspective, Abyss hosts the font files that are provided directly from Brand on our own CDN. --- ```jsx render H1 | Bold H2 | Bold H3 | Bold H4 | Bold H5 | Bold H6 | Bold ``` --- ## Headings (responsive/mobile) We lower the size of the heading elements to better fit smaller/mobile screens. The examples below are responsive with the viewport, so the mobile stylings will only appear if the viewport is 743px or lower. ```jsx render H1 | Bold H2 | Bold H3 | Bold H4 | Bold H5 | Bold {' '} H6 | Bold ``` --- ## Display Display sizes are headers with H1 tags that have a greater size than a regular H1. ```jsx render Display 1 Display 2 Display 3 ``` --- ## Display (responsive/mobile) We lower the size of the display elements to better fit smaller/mobile screens. The examples below are responsive with the viewport, so the mobile stylings will only appear if the viewport is 743px or lower. ```jsx render Display 1 Display 2 Display 3 ``` #### Recommendations

Always have an H1 heading for the page title
Keep headings scannable
Headings are always sentence-case
Do not use punctuation in headings

IMPORTANT: For way-finding, every page must have an H1 available (especially for screen readers) that describes the main purpose of the page such as “Claims & Benefits” --- ## Body copy text Enterprise Sans VF is the primary typeface for body copy. It is available in 3 weights — Bold, Medium, and Regular. All weights are available in italics. Regular copy is the default style for the majority of text on pages. Small copy is the secondary style for context on pages and is used for secondary text styles, as well as footnotes and legal messaging or less important content. Find further documentation in the [Text Component](/web/ui/text). ```jsx render P | LG | Bold P | LG | Medium P | LG | Regular P | MD | Bold P | MD | Medium P | MD | Regular P | SM | Bold P | SM | Medium P | SM | Regular P | XS | Bold P | XS | Medium P | XS | Regular P | 2XS | Bold P | 2XS | Medium P | 2XS | Regular ``` --- #### Recommendations - Italics are used only when referencing books, movies, albums or publication titles - Optum Sans xBold is used only when reversing type out of Optum Orange or on some photography for the sake of legibility. For this use, Brand approval is required through a Help Desk request. - Optum Sans Condensed is used for special cases only, such as legal and disclaimer copy. - People read 25% slower onscreen, and they skim rather than read - Web text should be short and scannable - Write no more than 50% of the text you would have used in a hardcopy publication - Write for scannability: don't require users to read long continuous blocks of text --- ## Accessibility It is best to have just one H1 on a page. Headings H2 through H6 help people understand the structure of the page and how content is organized. Headings also help people who use assistive technology move through the page content. Define page structure: - Describe the topic or purpose of a page in the document title - Start titles for browser tabs and windows with the page title and end them with the site name - Define sections of a page using headings and ARIA landmarks, including how sections should reflow for responsive breakpoints - If a page has a complex layout, it can be helpful to illustrate the tab order and reading order in design documentation - Group related items using a list structure - When text is used as a heading, assign appropriate heading tags (h1 to h6) - Follow heading hierarchy on every page: A single H1 and others in sequence Headings chosen for visual style rather than following hierarchy semantics. Doing so can make it difficult for people using assistive technology to navigate a page. --- Things to avoid or watch out for: Avoid using heading tags for visual effect alone. Heading tags convey meaning to assistive technology that helps people understand relationships in the page content. Always use HTML heading tags to style headings. A tag gives special meaning to the text that cannot be conveyed using visual formatting or CSS. People who use screen readers need to hear the information called out explicitly as a heading to be able to understand the purpose of the text. Be cautious about using heading tags in page footers, headers or to describe site navigation. Some U.S. states require heading tags to be used only within the main content area of a page. Review the page to confirm that an H1 is present and: - Visible whenever possible (not hidden using CSS unless the scenario requires it) - Appears as the first heading on the page Inspect the code and confirm that heading tags: - Are used in numerical order without gaps - Are used for headings (preferred); in cases where use of heading tags is not feasible, ARIA is used to indicate heading roles - Review the page with a screen reader to confirm that headings are presented in the order expected Specify type (and container) size using root em (rem) units. Rem units are sized relative to the base type size for the document, the base browser type size, rather than the size used within their containing element. Rems are preferred over ems, pixels or points. Em unit sizes can be challenging to manage due to parent-child relationship complexities. Points and pixels are static measurements that do not allow for a flexible presentation. Use rem units in CSS to specify type and container sizes. For reliable and flexible sizing, use rem units instead of pixels for media queries as well. Avoid specifying a fixed container height. Allowing the type size and padding to set the height of a container ensures the text is always visible and readable. It helps to avoid weird overflow or clipping issues. - Change the browser setting for text (font) size to anything larger than the default size and review the page. If is unreadable or unusable, then the text is not using rem units. --- id: typography-v2 title: Typography category: Brand description: Typography for Optum brands design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=3-16201&node-type=canvas&t=5TzFMfWfzXM0XMmI-0 pagination_prev: web/brand/optum/colors-v2 pagination_next: web/brand/optum/icon-brand customProps: { versionDefault: true } --- ## Overview Typography is the art and technique of arranging type to make written language legible. In the Abyss library, [Heading](/web/ui/heading), [Text](/web/ui/text), and [V2Link](/web/ui/link-v2) dive into the detail behind text formatting for Optum branding. More in-depth guidance on typography can be found below and on the Optum Brand Page. ```jsx render ``` --- **Note**: `Heading` and `Text` do not have V2 implemented yet. Some customization may be required to match current typography standards. --- ## Principles **Readability**: Ensure readability by keeping it simple with two typefaces that complement and contrast with one another. **Scalability**: Define and apply a typography scale that works in different platforms, no matter the screen size. **Hierarchy**: Creating a strong hierarchy is paramount to helping users identify where to look first, guiding them to the most important elements of the screen. Abyss typography uses minor 3rd scaling. The base is 16px for desktop and 14px for mobile. ## Sans-serif headings **Note**: The term "Abyss" prefixes fonts such as "Enterprise Sans VF" in the documentation under Font Family. This is because from a code perspective, Abyss hosts the font files that are provided directly from Brand on our own CDN. ### Display ```jsx render Display LG Display MD Display SM ``` ### Desktop ```jsx render XXL | Bold XL | Bold LG | Bold{' '} MD | Bold SM | Bold {' '} XS | Bold {' '} XXS | Bold ``` ### Mobile ```jsx render XXL | Bold XL | Bold LG | Bold{' '} MD | Bold SM | Bold {' '} XS | Bold XXS | Bold ``` ## Paragraph Size is the same in both desktop and mobile. ```jsx render LG | Bold LG | Med LG | Reg MD | Bold MD | Med MD | Reg SM | Bold SM | Med SM | Reg XS | Bold XS | Med XS | Reg ``` ## Links Size is the same in both desktop and mobile. ```jsx render LG | Underlined MD | Underlined SM | Underlined LG | Med MD | Med SM | Med ``` --- id: brandmark category: Brand title: Brandmark description: Logos/Brandmarks for UHC brands. pagination_prev: web/brand/uhc/get-started --- **Disclaimer:** Not all affiliate variant/color combinations are applicable, and some may not be available. Inapplicable combinations will render as empty. ```jsx import { Brandmark } from '@uhg-abyss/web/ui/Brandmark'; ``` ```jsx sandbox { component: 'Brandmark', inputs: [ { prop: 'size', type: 'string', }, { prop: 'affiliate', type: 'select', options: [ { label: 'aarp_extra_assurance_benefits', value: 'aarp_extra_assurance_benefits' }, { label: 'aarp_medicare_advantage_walgreens', value: 'aarp_medicare_advantage_walgreens' }, { label: 'aarp_medicare_advantage', value: 'aarp_medicare_advantage' }, { label: 'aarp_medicare_plans', value: 'aarp_medicare_plans' }, { label: 'aarp_medicare_prescription', value: 'aarp_medicare_prescription' }, { label: 'aarp_medicare_prescription_walgreens', value: 'aarp_medicare_prescription_walgreens' }, { label: 'aarp_medicare_supplement', value: 'aarp_medicare_supplement' }, { label: 'aarp_supplemental_personal_health', value: 'aarp_supplemental_personal_health' }, { label: 'community_plan', value: 'community_plan' }, { label: 'dental', value: 'dental' }, { label: 'dual_complete', value: 'dual_complete' }, { label: 'global', value: 'global' }, { label: 'hearing', value: 'hearing' }, { label: 'medicare_advantage', value: 'medicare_advantage' }, { label: 'group_medicare_advantage', value: 'group_medicare_advantage' }, { label: 'medicare_plans', value: 'medicare_plans' }, { label: 'medicare_solutions', value: 'medicare_solutions' }, { label: 'oxford', value: 'oxford' }, { label: 'student_resources', value: 'student_resources' }, { label: 'uhc', value: 'uhc' }, { label: 'vision', value: 'vision' }, ], }, { prop: 'variant', type: 'select', options: [ { label: 'lockup', value: 'lockup' }, { label: 'lockup_horizontal', value: 'lockup_horizontal' }, { label: 'u_mark', value: 'u_mark' }, { label: 'u_mark_horizontal', value: 'u_mark_horizontal' }, { label: 'monogram', value: 'monogram' }, { label: 'stacked_wordmark', value: 'stacked_wordmark' }, { label: 'wordmark', value: 'wordmark' }, ] }, { prop: 'color', type: 'select', options: [ { label: 'red', value: 'red' }, { label: 'white', value: 'white' }, { label: 'black', value: 'black' }, { label: 'blue', value: 'blue' }, { label: 'full', value: 'full' }, ] }, ] } ``` ## Brand Use the `brand` property to adjust which brand is being selected. ```jsx live ``` ## Size Use the `size` property to adjust the size of the brandmark. The size property sets the _width_ of the image. It can be a number of pixels, like `200px`, or a percent value, like `100%`. It can also be a string such as `$sm`, `$md`, or `$lg` to choose from a menu of pre-defined sizes. The `sizes` property controls this menu of pre-defined sizes. By default, it is set to this: ``` { sm: '100px', md: '150px', lg: '200px', } ``` ```jsx live ``` ## Affiliate Use the `affiliate` property to select the required brandmark affiliates. ```jsx live ``` ## Variant Use the `variant` property to select the required brandmark variants. ```jsx live ``` ## Color Use the `color` property to select available brandmark colors. ```jsx live ``` ```jsx render ``` ```jsx render ``` ```jsx render

Brandmarks

```
The source for these brandmarks can be found in the Brandmark Library. You can use the search functionality to find the required brandmark. Brandmarks can be searched using their affiliates, variants or colors. --- id: icon-brand slug: /web/brand/uhc/icon-brand category: Brand title: IconBrand description: Used to implement Brand icons and adapt their properties. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=3-15099 SourceIsTS: true --- ```jsx import { IconBrand } from '@uhg-abyss/web/ui/IconBrand'; ``` ```jsx sandbox { component: 'IconBrand', inputs: [ { prop: 'size', type: 'string', }, { prop: 'variant', type: 'select', options: [ { label: 'one tone', value: 'onetone' }, { label: 'two tone', value: 'twotone' }, { label: 'one tone w/ dark circle', value: 'onetonedarkcircle' }, { label: 'two tone w/ dark circle', value: 'twotonedarkcircle' }, { label: 'two tone w/ light circle', value: 'twotonelightcircle' }, ], }, { prop: 'icon', type: 'string', }, ] } ``` ## Usage Use `Icon` to implement custom SVG icons.
Use `IconSymbol` to implement Google's Material Design based icons.
Use `IconBrand` to implement UHC brand icons and adopt their properties. An icon is a graphical representation of an object, place or idea. Whereas, an IconBrand clearly communicate a brand's personality and identity. ## Icons Use the `icon` property to adjust which icon is being selected. **Note:** When using TypeScript, the `icon` property only accepts valid icon names. If an invalid icon name is provided, an error will be thrown. To verify that a given value is a valid icon name, use the [isValidAssetName tool](/web/tools/is-valid-asset-name) or use the `ValidIconBrandName` type: ```ts import { ValidIconBrandName } from '@uhg-abyss/web/ui/IconBrand'; let iconName: ValidIconBrandName; ``` ```jsx live ``` ## Size Use the `size` property to adjust the size of an icon by setting it to a specific number. The default size is set to 24. ```jsx live ``` ## Brand icon variants Use the `variant` property to change the style of Brand icons. Available variants are `twotonedarkcircle`, `twotonelightcircle`, `twotone`, `onetonedarkcircle`, and `onetone`. The default variant is `twotonedarkcircle`. ```jsx live onetonedarkcircle twotonedarkcircle twotonelightcircle onetone twotone ``` ```jsx render ``` ```jsx render ```

Meaningful or Control Icons

If the icon is being used in a setting where it is the only element providing meaning, then that same meaning should be conveyed to screen reader users. The below implementation provides examples of situations in which the property `isScreenReadable` should be set to true and the `title` property is required and should describe the purpose of the image. Example 1: An alert icon is used to convey a sense of urgency; there is adjacent text (“There is a data outage”) but the text doesn't include any words that convey urgency. So, in this case, the icon should have a text alternative such as “Alert” or “Warning”. ```jsx live

There is a data outage

Decorative Icons

If the icon is being used in a setting in which it just a decorative element (which is the default case for icons), then the icon should be ignored by screen readers. The below implementation provides example of which situations would be classified as decorative. Since the default of `isScreenReadable` is set to false no specific changes need to be made for decorative icons. Example 1: An alert icon is used next to an urgent message and the word “Alert” is included in the adjacent text. In this case, the icon becomes decorative in nature and should be ignored by screen readers. ```jsx live

Alert: There is a data outage

```
Example 2: An “X” material icon is used as a close button on a modal dialog; the word “Close” appears to the right of the button. In this case, the icon should be considered decorative and ignored by screen readers. ```jsx live

```

Useful Resources for Image Accessibility

- Image accessibility

Icon, IconBrand, and IconSymbol examples

Samples of all three icon components with and without titles (alt text): ```jsx live Decorative: No title Icons that duplicate or reinforce text content <> Github source <> Alert: Issues found! <> Close window Icon-only: Require title (alt text) Icons conveying information that is not part of the text (if any). <> Source <> Issues found! ```

Brand Icons

Abyss uses Brand's branded iconography that is designed to aid wayfinding, draw attention, and support messaging. The source for these design icons can be found in the Brand Icons Library. --- id: illustrated-icon-brand slug: /web/brand/uhc/illustrated-icon-brand category: Brand title: IllustratedIconBrand description: Used to implement UHC brand illustrated icons and adapt their properties. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=3-15099 sourceIsTS: true --- ```jsx import { IllustratedIconBrand } from '@uhg-abyss/web/ui/IllustratedIconBrand'; ``` ```tsx sandbox { component: 'IllustratedIconBrand', inputs: [ { prop: 'icon', type: 'string', }, { prop: 'size', type: 'string', }, { prop: 'color', type: 'select', options: [ { label: 'none', value: undefined }, { label: 'gold', value: 'gold' }, { label: 'orange', value: 'orange' }, { label: 'multicolor', value: 'multicolor' }, ] }, { prop: 'altText', type: 'string', }, ], } // Disclaimer: Not all icon/color combinations are applicable; inapplicable combinations will display as empty ``` ## Icon Use the `icon` prop to select the illustration to display. **Note:** When using TypeScript, the `icon` property only accepts valid icon names. If an invalid icon name is provided, an error will be thrown. To verify that a given value is a valid icon name, use the [isValidAssetName tool](/web/tools/is-valid-asset-name) or use the `ValidIllustratedIconBrandName` type: ```ts import { ValidIllustratedIconBrandName } from '@uhg-abyss/web/ui/IllustratedIconBrand'; let iconName: ValidIllustratedIconBrandName; ``` ```tsx live ``` ## Size Use the `size` property to adjust the width of the illustrated icon. This can be either a number (i.e. a pixel value) or a string. The default value is `"100%"`. The height of the illustration will scale proportionally to the width. ```tsx live ``` ## Color Use the `color` property to select available illustrated icon colors. The available colors are `"gold"`, `"orange"`, and `"multicolor"`. **Note:** Not all illustrated icons have any color variants. In such cases, omit the `color` prop; otherwise, the icon will not display. ```tsx live ``` ## Alt text Use the `altText` property to provide an accessible description of the illustrated icon. This text should be descriptive enough to convey the meaning of the icon. See the [Accessibility tab](/web/brand/uhc/illustrated-icon-brand?tab=accessibility) for more information. ```tsx live ``` ```jsx render ``` ```jsx render ```

Screen Reader Support

Illustrated icons are intended to be used as decorative images and as such, are ignored by screen readers by default. However, should a case arise in which an illustrated icon needs to be accessible, use the `altText` prop to provide accessible alt text to the image. This text should be descriptive enough to convey the meaning of the illustrated icon. ```tsx live ```

Illustrated Icon Source

The source for these illustrated icons can be found in the brand libraries. UnitedHealthCare Library

You can use the search functionality to find the required illustrated icons. Icons can be searched using their title or colors. --- id: illustration-brand slug: /web/brand/uhc/illustration-brand category: Brand title: IllustrationBrand description: Used to implement Brand illustrations and adapt their properties. sourceIsTS: true design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=3-15099 pagination_next: null --- ```jsx import { IllustrationBrand } from '@uhg-abyss/web/ui/IllustrationBrand'; ``` ```tsx sandbox { component: 'IllustrationBrand', inputs: [ { prop: 'brand', type: 'select', options: [ { label: 'optum', value: 'optum' }, { label: 'uhc', value: 'uhc' }, ], }, { prop: 'illustration', type: 'string', }, { prop: 'size', type: 'string', }, { prop: 'color', type: 'select', options: [ { label: 'primary', value: 'primary' }, { label: 'pacific', value: 'pacific' }, { label: 'white', value: 'white' }, ] }, { prop: 'variant', type: 'select', options: [ { label: '1', value: '1' }, { label: '2', value: '2' }, ], }, { prop: 'altText', type: 'string', }, ], } // Disclaimer: Not all brand/color combinations are applicable; inapplicable combinations will display as empty ``` ## Illustration Use the `illustration` prop to select the illustration to display. **Note:** When using TypeScript, the `icon` property only accepts valid icon names. If an invalid icon name is provided, an error will be thrown. To verify that a given value is a valid icon name, use the [isValidAssetName tool](/web/tools/is-valid-asset-name) or use the `ValidIllustrationBrandName` type: ```ts import { ValidIllustrationBrandName } from '@uhg-abyss/web/ui/IllustrationBrand'; let illustrationName: ValidIllustrationBrandName; ``` ```tsx live ``` ## Brand Use the `brand` prop to adjust which brand is selected. By default, the brand is set to the same brand as the brand used in the `ThemeProvider`. ```tsx live {/* This will change based on the theme selected in the navbar */} ``` ## Size Use the `size` property to adjust the width of the illustration. This can be either a number (i.e. a pixel value) or a string. The default value is `"100%"`. The height of the illustration will scale proportionally to the width. ```tsx live ``` ## Color Use the `color` property to select available illustration colors. The available colors are `"primary"`, `"pacific"`, and `"white"`. The default color is `"white""`. ```tsx live ``` ## Variant Some UHC illustrations have multiple variants of accent colors on the same background color. Use the `variant` prop to select the color combination. Valid values are `1` and `2`. ```tsx live ``` ## Alt text Use the `altText` property to provide an accessible description of the illustration. This text should be descriptive enough to convey the meaning of the illustration. See the [Accessibility tab](/web/brand/uhc/illustration-brand?tab=accessibility) for more information. ```tsx live ``` ```jsx render ``` ```jsx render ```

Screen Reader Support

Brand illustrations are intended to be used as decorative images and as such, are ignored by screen readers by default. However, should a case arise in which an illustration needs to be accessible, use the `altText` prop to provide accessible alt text to the image. This text should be descriptive enough to convey the meaning of the illustration. ```tsx live ```

Illustration Source

The source for these illustrations can be found in the brand libraries. UnitedHealthCare Library
Optum Library

You can use the search functionality to find the required illustration. Illustrations can be searched using their title, variants or colors. --- id: tokens category: Brand title: Tokens --- ## Overview Design tokens are the visual sub-atom variables of a design system. They contain UI data such as colors, border width, elevation, and even motion. They are used in the place of hard-coded values such as hex codes or pixels to maintain scalability and consistency. Think about them as recipe ingredients - you could add chocolate to a salad, but it won't be very tasty. You would only consider what is a standard salad ingredient - it's the same with tokens, they are a limited set of options that make sense for our product. **Further reading:**
[Nathan Curtis on Tokens in design systems](https://medium.com/eightshapes-llc/tokens-in-design-systems-25dd82d58421). ### Token hierarchy Abyss uses a 3-tier token system: - Core tier - the WHAT or the OPTIONS: contains primitive values, with no specific meaning - the name of the token and its raw value (HEX code for colors, and numbers for borders, corner radius, opacity, etc.) - Semantic tier - the HOW or the DECISIONS: communicates design decisions on the exact usage of a Core token system-wide. - Brand tokens - shorthand tokens to define common colors used throughout Abyss. ### Using tokens Before you can consume Abyss tokens, your project must be configured with our [ThemeProvider](/web/ui/theme-provider). This will allow you to access the tokens in your project. Tokens are used in place of hard-coded values such as hex codes or pixels. To use a token, you can reference it in your code using the `$` symbol followed by the token name. All Abyss components can accept tokens, when they are passed in using the [styled function](/web/tools/styled) or the [useToken hook](/web/hooks/use-token). Non-Abyss components can use the [styled](/web/tools/styled) function to accept tokens. #### Styled function To create a `div` component with a background color of `$core.color.brand.100`, you can leverage our [styled function](/web/tools/styled) and do the following: ```jsx sandbox () => { const Example = styled('div', { backgroundColor: '$core.color.brand.100', height: 100, width: 100, }); return ; }; ``` #### useToken hook Alternatively, you can use our [useToken Hook](/web/hooks/use-token) to directly access the value of a token. This is useful when you need the value of multiple tokens. Additionally, brand tokens are useful for quickly defining the color of components. ```jsx sandbox () => { const getColorToken = useToken('colors'); const green = getColorToken('$core.color.green.100'); const red = getColorToken('$core.color.red.120'); const interactive = getColorToken('$interactive1'); return ( <>

Core Tokens

Border Radius Tokens

`border-radius` tokens are used to define the `borderRadius` on components. ```jsx const Example = styled('div', { borderRadius: '$core.border-radius.md', }); ``` ```jsx render ``` ---

Spacing Tokens

Sizing Tokens

Color Tokens

`color` tokens are used to define the color of components. ```jsx const Example = styled('div', { backgroundColor: '$core.color.brand.100', }); ``` ```jsx render ```

Semantic Tokens

_**Note:** Click on the desired token to copy it to your clipboard._ ```jsx render ```

Brand Tokens

Brand tokens are useful for quickly defining the color of components. _**Note:** Click on the token row to copy the token to your clipboard._

Colors

Below is a list of brand tokens and their intended use cases. ```jsx const Example = styled('div', { backgroundColor: '$primary1', }); ``` ```jsx render ``` ---

Space

`space` tokens define the space between components. Generally, these will be used to define the `padding`, `margin`, or `gap` of components. ```jsx const Example = styled('div', { padding: '$md', }); ``` ```jsx render ``` ---

Accessibility

Color choices that are accessible ensure everyone can not only see every element on a page but also understand a specific, intended meaning. You want everyone to be able to see the difference between two colors right next to or on top of each other. Contrast refers to the perceived difference between foreground and background colors. People with low vision or color blindness and those with difficulty seeing the differences between colors can have trouble seeing where one element ends and another begins. As we age, the shape of our eyes changes and affects how we perceive color and how well we can distinguish color variations. If the contrast between different elements is too low, people may not be able to see them at all. Contrast is expressed as a ratio with the first number representing the foreground color and the second representing the background color. For example, 3:1 means the foreground item color is three times more intense or visible than the background value. Contrast rules apply to text as well as any content that conveys meaning, including icons, graphics, and form elements. Tools such as Colour Contrast Analyzer or WebAIM's online color contrast tool are useful for verifying contrast ratios. Color and contrast choices within a digital experience are accessible when people can: - See UI elements and content - Understand and interpret information - Take action We aim to provide a contrast ratio perceivable by all users. For this reason, UnitedHealthcare has embraced a minimum contrast ratio of 4.5:1 (foreground vs background) for UI elements and content that conveys meaning. Recommendations - Include color combinations, good contrast and poor contrast, in design documentation - Communicate meaning with more than just color, such as with color and descriptive text - Give focus indicators a unique presentation that meets contrast requirements on all backgrounds Test for a minimum contrast ratio of 4.5 to 1 for: - Non-bolded text smaller than 24 pixels (18 points) - Bold text smaller than 18 pixels (14 points) - Essential icons that are close to the body text size Test that non-text elements that communicate information meet a minimum contrast ratio of 3 to 1 for all states: - Icons - Data visualizations - Focus indicators - Controls, including their borders or boundaries - Non-bolded text at or above 24 pixels (18 points) - Bold text at or above 18 pixels (14 points) Don't worry about contrast for logos and disabled elements. Watch out for using color alone to communicate meaning. People who are color blind or blind cannot perceive the meaning by color alone. --- id: colors-v1 title: Colors category: Brand description: Colors of the UHC brand design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web?node-id=31937-113757&t=XUaEpQqeA2lOTxOM-0 pagination_prev: web/brand/uhc/tokens pagination_next: web/brand/uhc/typography-v1 customProps: { versionDefault: false } --- ## Overview Color differentiates our brands and helps create consistent experiences across our digital products. We use color to help our users know exactly what they need to focus on. We are committed to complying with the Web Content Accessibility Guidelines AA standard contrast ratios. To do this, choose primary, secondary, and extended colors that support usability by ensuring sufficient color contrast between elements. ```jsx render ``` --- ## Primary palette Our bold primary palette includes blues, neutrals and white and is used in logical ways throughout our products, marketing and sales to guide the eye and highlight important features. Utilizing our softer secondary colors, we bring warmth to the user experience to impart optimism and confidence. We use blue ($primary1) for primary actions, buttons, text links, for indicating progress and representing authentication. Neutral ($gray8) is used primarily for body text and headings, and white ($primary2) is used for page backgrounds. These colors are used in combination wherever a color theme may be desired. The Abyss theme can be adjusted on a case by case basis to allow for custom color components. ```jsx render Used as the main color of our components. Primarily used as the color that fills, outlines, or as the most prominent color. Used as the secondary color of our components. Primarily used for backgrounds or to contrast with $primary1. ``` --- ## Secondary Secondary colors are mostly used when a designer uses one or more of the brand's illustrated assets within a digital solution. ```jsx render Use as accents to bring warmth and lightness to our imagery and graphic treatments. Use as accents to bring warmth and lightness to our imagery and graphic treatments. Use as accents to bring warmth and lightness to our imagery and graphic treatments. ``` --- ## Accent The accent color is used to keep things fresh and interesting. We lean on this color more frequently when brand awareness is high, or on our own properties where we control the surrounding environment. ```jsx render Use in small details in brand elements. ``` --- ## Interactive Our interactive palette contains a variety of colors make every moment feel on-brand and every interaction informative. Each color is selected intentionally to provide meaningful feedback within our products. ```jsx render Use for elements the user can interact with such as links or icons. Use when implementing hover for an $interactive1 element. Use when implementing hover for a secondary button. Use for elements that have a high impact or that is highly stressed. ``` --- ### Tint Tints are reserved for containing boxes to highlight information. Tints are used for background fills, visual sectioning, and callouts. They appear behind scrollable content to add visual sectioning and accents. ```jsx render (Extra Light Blue) Use as a background color for delineation in layouts. Use in most cases where a tint is needed. Use for delineation in charts where Bright Blue 20% is already in use. ``` --- ## Data visualization Our Data Viz color palette contains a variety of colors with different categories. ### Primary palette Data Viz primary color palette. ```jsx render Use for data viz background and border. Use when implementing hover for an graph background. Use when implementing lighter background. ``` --- ### Secondary palette Data Viz secondary color palette. ```jsx render <> Use for data viz background and border. Use when implementing lighter background. Use for data viz background and border. Use when implementing lighter background. Use for data viz background and border. Use when implementing lighter background. Use for data viz background and border. Use when implementing lighter background. ``` --- ### Secondary status Data Viz status color palette. ```jsx render <> Use for data viz background and border status of graph. Use when implementing lighter background. Use for data viz background and border status of graph. Use when implementing lighter background. ``` --- ## Pastels Background Pastels appear in cards, cells and other smaller components adding visual sectioning and accents. They are used for small background fills, visual sectioning, and callouts. ```jsx render Use for small background fills, visual sectioning, and callouts. Use for small background fills, visual sectioning, and callouts. Use for small background fills, visual sectioning, and callouts. Use for small background fills, visual sectioning, and callouts. ``` ### Status ```jsx render Use to indicate success to the user such as upon completion of a form. Use for a hover or unfocused version of success. Use to indicate an error to the user such as when a form submission fails. Use for a hover or unfocused version of error. Use to indicate an error to the user such as when a form submission fails. Use to indicate a warning to the user such as when a form submission goes through but may be inaccurate. Use for a hover or unfocused version of warning. Use to indicate information to the user such as after a form is submitted and important information needs to be conveyed. Use for a hover or unfocused version of info. ``` ### Neutrals Neutrals have varying degrees of saturation that allow for the appropriate level of warmth across marketing and product. Typically they are used for text and subtle backgrounds when we don't want to draw too much attention to a particular touchpoint or convey information such as "disabled". Gray tints are limited to print when black is the only color option. ```jsx render Use White as a background or to contrast with darker colors. Implement white where it will never be necessary for the color theme to change. Use as a background color for delineation in Layouts. Use as a background color for delineation in Layouts. Use as a background color for delineation in Layouts. Use for additional delineation in Layouts. Use for disabled text only. Use for paragraph text. Use for labels and borders. When used on white background it may be used for legal copy. Use for headings h4-h6, body text and dark accents such as outlines, and actions. Use for headings, body text and dark accents such as outlines, and actions. Use for headings, body text and dark accents such as outlines, and actions. ``` --- ## Accessibility Color choices that are accessible ensure everyone can not only see every element on a page, but also understand a specific, intended meaning. You want everyone to be able to see the difference between two colors right next to or on top of each other. Contrast refers to the perceived difference between foreground and background colors. People with low vision or color blindness, and those who have difficulty seeing the differences between colors all can have trouble seeing where one element ends and another begins. As we age, the shape of our eyes changes and that affects both how we perceive color and how well we can distinguish variations in color. If the contrast between different elements is too low, people may not be able to see them at all. Contrast is expressed as a ratio with the first number representing the foreground color and the second representing the background color. For example, 3:1 means the foreground item color is three times more intense or visible than the background value. Contrast rules apply to text as well as any content that conveys meaning, including icons, graphics and form elements. Tools such as Colour Contrast Analyser or WebAIM's online color contrast tool are useful for verifying contrast ratios. Color and contrast choices within a digital experience are accessible when people can: - See UI elements and content - Understand and interpret information - Take action Our aim is to provide a contrast ratio that can be perceived by all users. For this reason, UnitedHealthcare has embraced a minimum contrast ratio of 4.5:1 (foreground vs background) for UI elements and content that convey meaning. Recommendations - Include color combinations, good contrast and poor contrast, in design documentation - Communicate meaning with more than just color, such as with color and descriptive text - Give focus indicators a unique presentation that meets contrast requirements on all backgrounds Test for a minimum contrast ratio 4.5 to 1 for: - Non-bolded text smaller than 24 pixels (18 points) - Bold text smaller than 18 pixels (14 points) - Essential icons that are close to body text size Test that non-text elements that communicate information meet a minimum contrast ratio of 3 to 1 for all states: - Icons - Data visualizations - Focus indicators - Controls, including their borders or boundaries - Non-bolded text at or above 24 pixels (18 points) - Bold text at or above 18 pixels (14 points) in size Don't worry about contrast for logos and disabled elements. Watch out for using color alone to communicate meaning. People who are color blind or blind cannot perceive the meaning by color alone. Useful Resources for Color Accessibility - Color and contrast accessibility - Accessibility testing for color contrast --- id: colors-v2 title: Colors category: Brand description: Colors of the UHC brand design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=1-16&node-type=canvas&t=9Oze02yWZcioUONN-0 pagination_prev: web/brand/uhc/tokens pagination_next: web/brand/uhc/typography-v2 customProps: { versionDefault: true } --- ## Overview Color differentiates our brands and helps create consistent experiences across our digital products. We use color to help our users know exactly what they need to focus on. We are committed to complying with the Web Content Accessibility Guidelines AA standard contrast ratios. To do this, choose primary, secondary, and extended colors that support usability by ensuring sufficient color contrast between elements. ```jsx render ``` --- ## Brand palette Primary colors communicate brand identity, widely used across interactive elements and is sparingly used for text - cta labels and headings. ```jsx render ``` --- ## Neutral palette Use neutrals for text, borders and backgrounds. ```jsx render ``` --- ## Semantic palette Communicates status and urgency. Use saturated colors for both text and high emphasis backgrounds. Use tint variations for backgrounds only. ```jsx render ``` --- ## Accent palette Use for emphasis and to communicate function. Does not have hierarchy. ```jsx render ``` ## Data visualization Used in our Data Visualization components. ```jsx render ``` --- ## Accessibility Color choices that are accessible ensure everyone can not only see every element on a page, but also understand a specific, intended meaning. You want everyone to be able to see the difference between two colors right next to or on top of each other. Contrast refers to the perceived difference between foreground and background colors. People with low vision or color blindness, and those who have difficulty seeing the differences between colors all can have trouble seeing where one element ends and another begins. As we age, the shape of our eyes changes and that affects both how we perceive color and how well we can distinguish variations in color. If the contrast between different elements is too low, people may not be able to see them at all. Contrast is expressed as a ratio with the first number representing the foreground color and the second representing the background color. For example, 3:1 means the foreground item color is three times more intense or visible than the background value. Contrast rules apply to text as well as any content that conveys meaning, including icons, graphics and form elements. Tools such as Colour Contrast Analyser or WebAIM's online color contrast tool are useful for verifying contrast ratios. Color and contrast choices within a digital experience are accessible when people can: - See UI elements and content - Understand and interpret information - Take action Our aim is to provide a contrast ratio that can be perceived by all users. For this reason, UnitedHealthcare has embraced a minimum contrast ratio of 4.5:1 (foreground vs background) for UI elements and content that convey meaning. Recommendations - Include color combinations, good contrast and poor contrast, in design documentation - Communicate meaning with more than just color, such as with color and descriptive text - Give focus indicators a unique presentation that meets contrast requirements on all backgrounds Test for a minimum contrast ratio 4.5 to 1 for: - Non-bolded text smaller than 24 pixels (18 points) - Bold text smaller than 18 pixels (14 points) - Essential icons that are close to body text size Test that non-text elements that communicate information meet a minimum contrast ratio of 3 to 1 for all states: - Icons - Data visualizations - Focus indicators - Controls, including their borders or boundaries - Non-bolded text at or above 24 pixels (18 points) - Bold text at or above 18 pixels (14 points) in size Don't worry about contrast for logos and disabled elements. Watch out for using color alone to communicate meaning. People who are color blind or blind cannot perceive the meaning by color alone. Useful Resources for Color Accessibility - Color and contrast accessibility - Accessibility testing for color contrast --- id: get-started category: Brand title: Brand description: The partnership with the UHC brand team solidifies the foundation of Abyss digital assets which unify our brand experience. hideHeaderActions: true pagination_prev: null pagination_next: web/brand/uhc/brandmark --- ## Latest updates **Note:** Abyss supports both Enterprise Sans and UHC Sans. The default font is UHC Sans. To use Enterprise Sans, refer to this [link](/web/tools/create-theme-uhc). ## Brand assets --- id: typography-v1 title: Typography category: Brand description: Typography for UHC brands pagination_prev: web/brand/uhc/colors-v2 pagination_next: web/brand/uhc/icon-brand customProps: { versionDefault: false } --- ## Overview Typography is the art and technique of arranging type to make written language legible. In the Abyss library, [Heading](/web/ui/heading) and [Text](/web/ui/text) dive into the detail behind text formatting for UHC branding. More in depth guidance on typography can be found below and in the UHC Brand Page. ```jsx render ``` --- ## Headings Headings identify chunks of related content on a page and establish the hierarchy showing how those chunks of content relate to each other. If someone reads only the headings on a page, they will get a general understanding of the information presented. HTML defines six heading levels: H1 to H6. H1 identifies an entire page, or overall topic, and is the most important level. There should only be 1 H1 per page. Find further documentation in the [Heading](/web/ui/heading) component. **Note**: The term "Abyss" prefixes fonts such as "Enterprise Sans VF" in the documentation under Font Family. This is because from a code perspective, Abyss hosts the font files that are provided directly from Brand on our own CDN. ```jsx render H1 | SemiBold H2 | SemiBold H3 | SemiBold H4 | Bold H5 | Bold H6 | Bold ``` --- ## Headings (responsive/mobile) We lower the size of the heading elements to better fit smaller/mobile screens. The examples below are responsive with the viewport, so the stylings will only appear if the viewport is 743px or lower. ```jsx render H1 | SemiBold H2 | SemiBold H3 | SemiBold H4 | Bold H5 | Bold H6 | Bold ``` --- ## Display Display sizes are headers with H1 tags that have a greater size than a regular H1. ```jsx render Display 1 Display 2 Display 3 ``` --- ## Display (responsive/mobile) We lower the size of the display elements to better fit smaller/mobile screens. The examples below are responsive with the viewport, so the mobile stylings will only appear if the viewport is 743px or lower. ```jsx render Display 1 Display 2 Display 3 ``` #### Recommendations

Always have an H1 heading for the page title
Keep headings scannable
Headings are always sentence-case
Do not use punctuation in headings

IMPORTANT: For way-finding, every page must have an H1 available (especially for screen readers) that describes the main purpose of the page such as “Claims & Benefits” --- ## Body copy text Enterprise Sans VF is our primary typeface for body copy. It is available in 3 weights — Bold, Medium, and Regular. All weights are available in italics. Regular copy is the default style for the majority of text on pages. Small copy is the secondary style for context on pages and is used for secondary text styles, as well as footnotes and legal messaging or less important content. Find further documentation in the [Text Component](/web/ui/text). ```jsx render P | LG | Bold P | LG | Medium P | LG | Regular P | MD | Bold P | MD | Medium P | MD | Regular P | SM | Bold P | SM | Medium P | SM | Regular P | XS | Bold P | XS | Medium P | XS | Regular P | 2XS | Bold P | 2XS | Medium P | 2XS | Regular ``` --- #### Recommendations - Italics are used only when referencing books, movies, albums or publication titles - People read 25% slower onscreen, and they skim rather than read - Web text should be short and scannable - Write no more than 50% of the text you would have used in a hardcopy publication - Write for scannability: don't require users to read long continuous blocks of text --- ## Accessibility It is best to have just one H1 on a page. Headings H2 through H6 help people understand the structure of the page and how content is organized. Headings also help people who use assistive technology move through the page content. Define page structure: - Describe the topic or purpose of a page in the document title - Start titles for browser tabs and windows with the page title and end them with the site name - Define sections of a page using headings and ARIA landmarks, including how sections should reflow for responsive breakpoints - If a page has a complex layout, it can be helpful to illustrate the tab order and reading order in design documentation - Group related items using a list structure - When text is used as a heading, assign appropriate heading tags (h1 to h6) - Follow heading hierarchy on every page: A single H1 and others in sequence Headings chosen for visual style rather than following hierarchy semantics. Doing so can make it difficult for people using assistive technology to navigate a page. --- Things to avoid or watch out for: Avoid using heading tags for visual effect alone. Heading tags convey meaning to assistive technology that helps people understand relationships in the page content. Always use HTML heading tags to style headings. A tag gives special meaning to the text that cannot be conveyed using visual formatting or CSS. People who use screen readers need to hear the information called out explicitly as a heading to be able to understand the purpose of the text. Be cautious about using heading tags in page footers, headers or to describe site navigation. Some U.S. states require heading tags to be used only within the main content area of a page. Review the page to confirm that an H1 is present and: - Visible whenever possible (not hidden using CSS unless the scenario requires it) - Appears as the first heading on the page Inspect the code and confirm that heading tags: - Are used in numerical order without gaps - Are used for headings (preferred); in cases where use of heading tags is not feasible, ARIA is used to indicate heading roles - Review the page with a screen reader to confirm that headings are presented in the order expected Specify type (and container) size using root em (rem) units. Rem units are sized relative to the base type size for the document, the base browser type size, rather than the size used within their containing element. Rems are preferred over ems, pixels or points. Em unit sizes can be challenging to manage due to parent-child relationship complexities. Points and pixels are static measurements that do not allow for a flexible presentation. Use rem units in CSS to specify type and container sizes. For reliable and flexible sizing, use rem units instead of pixels for media queries as well. Avoid specifying a fixed container height. Allowing the type size and padding to set the height of a container ensures the text is always visible and readable. It helps to avoid weird overflow or clipping issues. - Change the browser setting for text (font) size to anything larger than the default size and review the page. If is unreadable or unusable, then the text is not using rem units. --- id: typography-v2 title: Typography category: Brand description: Typography for UHC brands design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=3-16201&node-type=canvas&t=5TzFMfWfzXM0XMmI-0 pagination_prev: web/brand/uhc/colors-v2 pagination_next: web/brand/uhc/icon-brand customProps: { versionDefault: true } --- ## Overview Typography is the art and technique of arranging type to make written language legible. In the Abyss library, [Heading](/web/ui/heading), [Text](/web/ui/text), and [V2Link](/web/ui/link-v2) dive into the detail behind text formatting for UHC branding. More in-depth guidance on typography can be found below and on the UHC Brand Page. ```jsx render ``` --- **Note**: `Heading` and `Text` do not have V2 implemented yet. Some customization may be required to match current typography standards. ## Principles **Readability**: Ensure readability by keeping it simple with two typefaces that complement and contrast with one another. **Scalability**: Define and apply a typography scale that works in different platforms, no matter the screen size. **Hierarchy**: Creating a strong hierarchy is paramount to helping users identify where to look first, guiding them to the most important elements of the screen. Abyss typography uses minor 3rd scaling. The base is 16px for desktop and 14px for mobile. ## Serif headings (UHC only) **Note**: The term "Abyss" prefixes fonts such as "Enterprise Sans VF" in the documentation under Font Family. This is because from a code perspective, Abyss hosts the font files that are provided directly from Brand on our own CDN. ### Desktop ```jsx render () => { const fontFamily = 'AbyssUHCSerif, Georgia Bold, serif'; const themeOverride = { theme: { fonts: { heading: fontFamily, primary: fontFamily }, }, }; const theme = createTheme('uhc', themeOverride); return ( XL | Semibold LG | Semibold MD | Semibold SM | Semibold XS | Semibold ); }; ``` ### Mobile ```jsx render () => { const fontFamily = 'AbyssUHCSerif, Georgia Bold, serif'; const themeOverride = { theme: { fonts: { heading: fontFamily, primary: fontFamily }, }, }; const theme = createTheme('uhc', themeOverride); return ( XL | Semibold LG | Semibold MD | Semibold SM | Semibold XS | Semibold ); }; ``` ## Sans-serif headings ### Display ```jsx render () => { const abyssTheme = useAbyssTheme(); const fontFamily = abyssTheme.fonts.primary; const themeOverride = { theme: { fonts: { heading: fontFamily }, }, }; const theme = createTheme('uhc', themeOverride); return ( Display LG Display MD Display SM ); }; ``` ### Desktop ```jsx render () => { const abyssTheme = useAbyssTheme(); const fontFamily = abyssTheme.fonts.primary; const themeOverride = { theme: { fonts: { heading: fontFamily }, }, }; const theme = createTheme('uhc', themeOverride); return ( XXL | Bold XL | Bold LG | Bold{' '} MD | Bold SM | Bold {' '} XS | Bold {' '} XXS | Bold ); }; ``` ### Mobile ```jsx render () => { const abyssTheme = useAbyssTheme(); const fontFamily = abyssTheme.fonts.primary; const themeOverride = { theme: { fonts: { heading: fontFamily }, }, }; const theme = createTheme('uhc', themeOverride); return ( XXL | Bold XL | Bold LG | Bold{' '} MD | Bold SM | Bold {' '} XS | Bold XXS | Bold ); }; ``` ## Paragraph Size is the same in both desktop and mobile. ```jsx render LG | Bold LG | Med LG | Reg MD | Bold MD | Med MD | Reg SM | Bold SM | Med SM | Reg XS | Bold XS | Med XS | Reg ``` ## Links Size is the same in both desktop and mobile. ```jsx render LG | Underlined MD | Underlined SM | Underlined LG | Med MD | Med SM | Med ``` --- id: brandmark category: Brand title: Brandmark description: Logos/Brandmarks for UHG brands. pagination_prev: web/brand/uhg/get-started --- ```jsx import { Brandmark } from '@uhg-abyss/web/ui/Brandmark'; ``` ```jsx sandbox { component: 'Brandmark', inputs: [ { prop: 'size', type: 'string', }, { prop: 'affiliate', type: 'select', options: [ { label: 'uhg', value: 'uhg' }, ], }, { prop: 'variant', type: 'select', options: [ { label: 'lockup', value: 'lockup' }, ] }, { prop: 'color', type: 'select', options: [ { label: 'blue', value: 'blue' }, { label: 'black', value: 'black' }, { label: 'white', value: 'white' }, ] }, ] } ``` ## Brand Use the `brand` property to adjust which brand is being selected. ```jsx live ``` ## Size Use the `size` property to adjust the size of the brandmark. The size property sets the _width_ of the image. It can be a number of pixels, like `200px`, or a percent value, like `100%`. It can also be a string such as `$sm`, `$md`, or `$lg` to choose from a menu of pre-defined sizes. The `sizes` property controls this menu of pre-defined sizes. By default, it is set to this: ``` { sm: '100px', md: '150px', lg: '200px', } ``` ```jsx live ``` ## Variant Use the `variant` property to select the required brandmark variants. ```jsx live ``` ## Color Use the `color` property to select available brandmark colors. ```jsx live ``` ```jsx render ``` ```jsx render ``` Brandmarks uses the image name describes the content in the image. ```jsx render

Brandmarks

```
You can use the search functionality to find the required brandmark. Brandmarks can be searched using their affiliates, variants or colors. --- id: icon-brand slug: /web/brand/uhg/icon-brand category: Brand title: IconBrand description: Used to implement Brand icons and adapt their properties. SourceIsTS: true --- ```jsx import { IconBrand } from '@uhg-abyss/web/ui/IconBrand'; ``` ```jsx sandbox { component: 'IconBrand', inputs: [ { prop: 'size', type: 'string', }, { prop: 'variant', type: 'select', options: [ { label: 'one tone', value: 'onetone' }, { label: 'two tone', value: 'twotone' }, { label: 'one tone w/ dark circle', value: 'onetonedarkcircle' }, { label: 'two tone w/ dark circle', value: 'twotonedarkcircle' }, { label: 'two tone w/ light circle', value: 'twotonelightcircle' }, ], }, { prop: 'icon', type: 'string', }, ] } ``` ## Usage Use `Icon` to implement custom SVG icons.
Use `IconSymbol` to implement Google's Material Design based icons.
Use `IconBrand` to implement UHG brand icons and adopt their properties. An icon is a graphical representation of an object, place or idea. Whereas, an IconBrand clearly communicate a brand's personality and identity. ## Icons Use the `icon` property to adjust which icon is being selected. **Note:** When using TypeScript, the `icon` property only accepts valid icon names. If an invalid icon name is provided, an error will be thrown. To verify that a given value is a valid icon name, use the [isValidAssetName tool](/web/tools/is-valid-asset-name) or use the `ValidIconBrandName` type: ```ts import { ValidIconBrandName } from '@uhg-abyss/web/ui/IconBrand'; let iconName: ValidIconBrandName; ``` ```jsx live ``` ## Size Use the `size` property to adjust the size of an icon by setting it to a specific number. The default size is set to 24. ```jsx live ``` ## Brand icon variants Use the `variant` property to change the style of Brand icons. Available variants are `twotonedarkcircle`, `twotonelightcircle`, `twotone`, `onetonedarkcircle`, and `onetone`. The default variant is `twotonedarkcircle`. ```jsx live onetonedarkcircle twotonedarkcircle twotonelightcircle onetone twotone ``` ```jsx render ``` ```jsx render ```

Meaningful or Control Icons

There is a data outage

Decorative Icons

Alert: There is a data outage

```

Useful Resources for Image Accessibility

- Image accessibility

Icon, IconBrand, and IconSymbol examples

Brand Icons

Abyss uses Brand's branded iconography that is designed to aid wayfinding, draw attention and support messaging. The source for these design icons can be found in the UHG Brand Icons Library. --- id: illustrated-icon-brand slug: /web/brand/uhg/illustrated-icon-brand category: Brand title: IllustratedIconBrand description: Used to implement UHC brand illustrated icons and adapt their properties. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=3-15099 sourceIsTS: true --- ## Unavailable Illustrated icons for UHG are currently unavailable. Please see the docs for [UHC](/web/brand/uhc/illustrated-icon-brand) for available illustrated icons. --- id: illustration-brand slug: /web/brand/uhg/illustration-brand category: Brand title: IllustrationBrand description: Used to implement Brand illustrations and adapt their properties. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=3-15099 pagination_next: null --- ## Unavailable Brand illustrations for UHG are currently unavailable. Please see the docs for [UHC](/web/brand/uhc/illustration-brand) or [Optum](/web/brand/optum/illustration-brand) for available illustrations. --- id: colors title: Colors category: Brand description: Colors of the UHG brand design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web?node-id=35091-117338&t=XUaEpQqeA2lOTxOM-0 pagination_prev: web/brand/uhg/brandmark pagination_next: web/brand/uhg/typography --- ## Overview Color differentiates our brands and helps create consistent experiences across our digital products. We use color to help our users know exactly what they need to focus on. We are committed to complying with the Web Content Accessibility Guidelines AA standard contrast ratios. To do this, choose primary, secondary, and extended colors that support usability by ensuring sufficient color contrast between elements. --- ## Primary Our bold primary palette is used in logical ways throughout our products, marketing and sales to guide the eye and highlight important features. Utilizing our softer secondary colors, we bring warmth to the user experience to impart optimism and confidence. We use blue ($primary1) for primary actions, buttons, text links, for indicating progress and representing authentication. These colors are used in combination wherever a color theme may be desired. The Abyss theme can be adjusted on a case by case basis to allow for custom color components. ```jsx render Primary typography, navigation bar, button background, and component headers. This is the most common occuring blue, and should be used the most often. Used as the secondary color of our components. Primarily used for backgrounds or to contrast with $primary1. ``` --- ## Secondary Secondary colors are mostly used when a designer uses one or more of the brand's illustrated assets within a digital solution. ```jsx render Use as accents to bring warmth and lightness to our imagery and graphic treatments. Use as accents to bring warmth and lightness to our imagery and graphic treatments. Use as accents to bring warmth and lightness to our imagery and graphic treatments. ``` --- ## Accent The accent color is used to keep things fresh and interesting. We lean on this color more frequently when brand awareness is high, or on our own properties where we control the surrounding environment. ```jsx render Use in communications, but can vary in amount from larger floods of color to small details in brand elements. Use in communications, but can vary in amount from larger floods of color to small details in brand elements. ``` --- ## Interactive Our interactive palette contains a variety of colors make every moment feel on-brand and every interaction informative. Each color is selected intentionally to provide meaningful feedback within our products. ```jsx render Use for elements the user can interact with such as links or icons. Use when implementing hover for an $interactive1 element. Use when implementing hover for a secondary button. ``` --- ### Tint Tints are reserved for containing boxes to highlight information. Tints are used for background fills, visual sectioning, and callouts. They appear behind scrollable content to add visual sectioning and accents. ```jsx render (Extra Light Blue) Use as a background color for delineation in layouts. Use in most cases where a tint is needed. Use for delineation in charts where Bright Blue 20% is already in use. ``` --- ## Data visualization Our Data Viz color palette contains a variety of colors with different categories. ### Primary palette Data Viz primary color palette. ```jsx render Use for data viz background and border. Use when implementing hover for an graph background. Use when implementing lighter background. ``` --- ### Secondary palette Data Viz secondary color palette. ```jsx render <> Use for data viz background and border. Use when implementing hover for an graph background. Use when implementing lighter background. Use for data viz background and border. Use when implementing hover for an graph background. Use when implementing lighter background. Use for data viz background and border. Use when implementing hover for an graph background. Use when implementing lighter background. Use for data viz background and border. Use when implementing hover for an graph background. Use when implementing lighter background. ``` --- ### Secondary status Data Viz status color palette. ```jsx render <> Use for data viz background and border status of graph. Use when implementing hover for an graph background status. Use when implementing lighter background. Use for data viz background and border status of graph. Use when implementing hover for an graph background status. Use when implementing lighter background. ``` --- ## Supporting Supporting colors are primarily used for infographics and data visualizations. ```jsx render Use in digital spaces, for infographic and data visualizations. Use in digital spaces, for infographic and data visualizations. Use in digital spaces, for infographic and data visualizations. Use in digital spaces, for infographic and data visualizations. Use in digital spaces, for infographic and data visualizations. Use in digital spaces, for infographic and data visualizations. ``` ### Status ```jsx render Use to indicate success to the user such as upon completion of a form. Use for a hover or unfocused version of success. Use to indicate an error to the user such as when a form submission fails. Use for a hover or unfocused version of error. Use to indicate a warning to the user such as when a form submission goes through but may be inaccurate. Use for a hover or unfocused version of warning. Use to indicate information to the user such as after a form is submitted and important information needs to be conveyed. Use for a hover or unfocused version of info. ``` ### Neutrals Neutrals have varying degrees of saturation that allow for the appropriate level of warmth across marketing and product. Typically they are used for text and subtle backgrounds when we don't want to draw too much attention to a particular touchpoint or convey information such as "disabled". Gray tints are limited to print when black is the only color option. ```jsx render Use White as a background or to contrast with darker colors. Implement white where it will never be necessary for the color theme to change. Use as a background color for delineation in Layouts. Use as a background color for delineation in Layouts. Use as a background color for delineation in Layouts. Use for additional delineation in Layouts. Use for disabled text only. Use for paragraph text. Use for labels and borders. When used on white background it may be used for legal copy. Use for headings h4-h6, body text and dark accents such as outlines, and actions Use for headings, body text and dark accents such as outlines, and actions. Use for headings, body text and dark accents such as outlines, and actions. ``` --- ## Accessibility Color choices that are accessible ensure everyone can not only see every element on a page, but also understand a specific, intended meaning. You want everyone to be able to see the difference between two colors right next to or on top of each other. Contrast refers to the perceived difference between foreground and background colors. People with low vision or color blindness, and those who have difficulty seeing the differences between colors all can have trouble seeing where one element ends and another begins. As we age, the shape of our eyes changes and that affects both how we perceive color and how well we can distinguish variations in color. If the contrast between different elements is too low, people may not be able to see them at all. Contrast is expressed as a ratio with the first number representing the foreground color and the second representing the background color. For example, 3:1 means the foreground item color is three times more intense or visible than the background value. Contrast rules apply to text as well as any content that conveys meaning, including icons, graphics and form elements. Tools such as Colour Contrast Analyser or WebAIM's online color contrast tool are useful for verifying contrast ratios. Color and contrast choices within a digital experience are accessible when people can: - See UI elements and content - Understand and interpret information - Take action Our aim is to provide a contrast ratio that can be perceived by all users. For this reason, UnitedHealthcare has embraced a minimum contrast ratio of 4.5:1 (foreground vs background) for UI elements and content that convey meaning. Recommendations - Include color combinations, good contrast and poor contrast, in design documentation - Communicate meaning with more than just color, such as with color and descriptive text - Give focus indicators a unique presentation that meets contrast requirements on all backgrounds Test for a minimum contrast ratio 4.5 to 1 for: - Non-bolded text smaller than 24 pixels (18 points) - Bold text smaller than 18 pixels (14 points) - Essential icons that are close to body text size Test that non-text elements that communicate information meet a minimum contrast ratio of 3 to 1 for all states: - Icons - Data visualizations - Focus indicators - Controls, including their borders or boundaries - Non-bolded text at or above 24 pixels (18 points) - Bold text at or above 18 pixels (14 points) in size Don't worry about contrast for logos and disabled elements. Watch out for using color alone to communicate meaning. People who are color blind or blind cannot perceive the meaning by color alone. Useful Resources for Color Accessibility - Color and contrast accessibility - Accessibility testing for color contrast --- id: get-started category: Brand title: Brand description: The partnership with the UHG brand team solidifies the foundation of Abyss digital assets which unify our brand experience. hideHeaderActions: true pagination_prev: null pagination_next: web/brand/uhg/brandmark --- ## Latest updates ## Brand assets --- id: typography title: Typography category: Brand description: Typography for UHG brands pagination_prev: web/brand/uhg/colors pagination_next: web/brand/uhg/icon-brand --- ## Overview Typography is the art and technique of arranging type to make written language legible. In the Abyss library, [Heading](/web/ui/heading) and [Text](/web/ui/text) dive into the detail behind text formatting for UHG branding. More in depth guidance on typography can be found below and in the UHG Brand Resources Sharepoint. --- ## Headings Headings identify chunks of related content on a page and establish the hierarchy showing how those chunks of content relate to each other. If someone reads only the headings on a page, they will get a general understanding of the information presented. HTML defines six heading levels: H1 to H6. H1 identifies an entire page, or overall topic, and is the most important level. There should only be 1 H1 per page. Find further documentation in the [Heading](/web/ui/heading) component. **Note**: The term "Abyss" prefixes fonts such as "Enterprise Sans VF" in the documentation under Font Family. This is because from a code perspective, Abyss hosts the font files that are provided directly from Brand on our own CDN. ```jsx render H1 | Bold H2 | Bold H3 | Bold H4 | Bold H5 | Bold H6 | Bold ``` --- ## Headings (responsive/mobile) We lower the size of the heading elements to better fit smaller/mobile screens. The examples below are responsive with the viewport, so the mobile stylings will only appear if the viewport is 743px or lower. ```jsx render H1 | Bold H2 | Bold H3 | Bold H4 | Bold H5 | Bold H6 | Bold ``` --- ## Display Display sizes are headers with H1 tags that have a greater size than a regular H1. ```jsx render Display 1 Display 2 Display 3 ``` --- ## Display (responsive/mobile) We lower the size of the display elements to better fit smaller/mobile screens. The examples below are responsive with the viewport, so the mobile stylings will only appear if the viewport is 743px or lower. ```jsx render Display 1 Display 2 Display 3 ``` #### Recommendations

Always have an H1 heading for the page tile
Keep headings scannable
Headings are always sentence-case
Do not use punctuation in headings

{step.seqNo} {step.title} {step.description} ); })} ); }; ``` ## Benefits of contributing to a design system Product managers will be able to capitalize on the efficiencies gained by leveraging the collective knowledge and shared solutions that are accessible through the broader Abyss community. The benefits of staffing a dedicated Admiral on your delivery team include: ```jsx render () => { const StyledHead = styled(Heading, { fontWeight: '$bold !important', fontSize: '$md !important', display: 'inline-block', lineHeight: '20px !important', fontFamily: '$primary !important', }); const StyledList = styled('li', { marginBottom: '15px', }); const admiralExpectations = [ { title: 'Reduced Design Fragmentation:', description: "When individual teams are designing within disconnected, siloed environments, they'll often discover multiple different approaches to solving the same problem. Admirals can act as advisors to prevent this additional overhead from occurring by raising awareness of pre-existing solutions. Contributing to the design system helps ensure that all products or services for providers and consumers within the enterprise have a consistent look and feel, which improves the user experience and helps establish a strong brand identity.", }, { title: 'Promote Design Growth:', description: 'For a designer who is eager to progress further along their career path, the Admirals program offers an elevated set of responsibilities for overseeing projects. Since this role is both highly technical and relationship-oriented, coupled with a sense of personal accountability, Admirals can leverage this experience to explore their interest in management or leadership roles. Track your contributions and retain them for your annual reviews!', }, { title: 'Accountability for Essential Tasks:', description: 'Product teams are often overburdened with upkeep and maintenance-related chores because they are given a lower priority than feature work. By assigning an Admiral to each project, teams can verify that quality, versioning, accessibility, and peer review processes are being observed.', }, { title: 'Optimized Outcomes:', description: 'Admirals reduce the time and cost of design through specialization and economies of scale. By tapping into a centralized community of knowledge, skills, and experience, the Admirals program can streamline access to those scarce capabilities while also facilitating balanced, cohesive design teams.', }, { title: 'Scalability:', description: 'A well-designed enterprise design system can accommodate growth and change, making adapting to new technologies, products, and services easier.', }, { title: 'Accessibility:', description: 'A design system can help ensure that products and services are accessible to all users, including those with disabilities, by providing guidelines and components that meet accessibility standards.', }, { title: 'Innovation:', description: 'By contributing to a design system, designers and developers can explore new ideas and approaches, leading to innovative solutions that benefit the enterprise and its customers.', }, ]; return (

{ele.title} {' '} {ele.description}

); }; ``` ```jsx render () => { const admiralMeets = [ { title: 'Weekly Check-In', duration: '2x per sprint, 30 minutes', purpose: 'For Admirals who are assigned tickets in the current sprint, this meeting is set up to discuss any blockers and ticket updates.', borderColor: '#00BED5', }, { title: 'Design Grooming', duration: '1x per sprint, 15-30 minutes', purpose: 'To discuss incoming tickets, capacity allowance for the next sprint, and any final updates from the current sprint.', borderColor: '#FF6814', }, { title: 'Abyss Refinement', duration: '1x per sprint, 60 minutes', purpose: 'To hand off current projects to the engineering team. This is the deadline for all current tickets. Components and documentation should be ready to be discussed in detail with the engineering team.', borderColor: '#F5B700', }, ]; return ( When Do Admirals Meet? Admirals meet numerous times during a sprint The Abyss Admiral team hosts a series of three meetings throughout a sprint to connect with designers, discuss updates, and provide support for any blockers. {admiralMeets.map((meet) => { return ( {meet.title} Duration: {meet.duration} Purpose: {meet.purpose} ); })} ); }; ``` ## Admiral expectations An Admiral is a voluntary position with many benefits for the Admiral, the product teams, and the Abyss team. To ensure that this position is the right fit, Abyss has some general expectations for Admirals to make the best use of everyone's time. ```jsx render () => { const StyledHead = styled(Heading, { fontWeight: '$bold !important', fontSize: '$md !important', display: 'inline-block', lineHeight: '20px !important', fontFamily: '$primary !important', }); const StyledList = styled('li', { marginBottom: '15px', }); const admiralExpectations = [ { title: 'Time commitment', description: "There may be sprints where you are unable to contribute, and that's just fine. We expect there to be fluctuation between your regular product team work and the Admiral work. To maintain the status of Admiral, we ask for a minimum of one contribution per quarter (or 6 sprints). Thus, we recommend that Admirals contribute 10-30% of their sprint to Abyss (8-24 hours).", }, { title: 'Timelines', description: "Abyss has deadlines, just like product teams. To meet these, we ask that Admirals complete their tickets by the due date of the ticket and request help from a Design Lead when needed. We're happy to help!", }, { title: 'Attend required meetings', description: "If you have allotted time to contribute in the current sprint, there are required meetings that you will need to attend in order to complete the ticket. Of the capacity you allot, make sure to account for roughly 2.5 hours of meetings over the two-week sprint. If you allotted 10% (8 hours) of your sprint, that's already almost one third of your Admiral sprint time. So, if your time commitment is less than 10%, consider passing over the sprint.", }, ]; return (

{`${i + 1}. `}{' '} {`${ele.title}:`} {' '} {ele.description}

); }; ``` --- id: design-checklist title: Design Checklist --- ## Overview Welcome to Abyss! If you’re just starting out designing with Abyss, you’re in the right place. Here’s a checklist of everything you need to get up and running. Abyss design kit is available in Figma through our enterprise account (Optum/UHG) ## Create Figma account ## Using the designer toolkit ## Review updates --- id: design-kit title: Design Kit --- ## Overview ## Designer toolkit ## Guidance ## Accessibility ## Contact us --- id: overview title: Overview --- Welcome to the `create-abyss-app` landing page! This powerful tool is designed to streamline the development of complex applications by utilizing a monorepo structure to manage both frontend and backend projects seamlessly. Whether you're building a dynamic web application or a robust API, `create-abyss-app` equips you with the tools necessary for modern, scalable, and efficient development. ## Advantages - **Zero Configuration Setup** - All tools are already configured that are essential for React development. Tools like Webpack (for bundling your code) and Babel (for using modern JavaScript features). - **Easy To Use** - You can start developing and see those results immediately. - **Optimized Build Output** - Provides optimized production builds out of the box, including minification, concatenation, and efficient loading (e.g., code splitting). - **Community and Support:** - Many team are already using the `create-abyss-app`, it offers significant support, regular updates, and a large number of resources for troubleshooting. ## Project structure An Abyss application is divided into two primary products: a frontend and a backend. This is represented as two JavaScript projects within a single monorepo. A monorepo is a software development strategy where code for many projects is stored in the same repository. We use NPM Workspaces to make it easy to operate across both projects while keeping them in a single Git repository. The frontend project is called `web` and the backend project is called `api`. They are independent projects; the code on the web side will end up running in the user's browser while code on the API side will run on a server somewhere. The API source includes a NodeJS server which manages your business logic through GraphQL and REST endpoints. The web source includes a NextJS server which invokes your API and renders components through a React UI. By separating these two development paradigms, you can build applications that are well-organized and able to scale to meet the needs of your business. In addition to the `web` and `api` projects, the Abyss monorepo includes a third product called `workshop`. This is where [Parcels](/foundations/parcels/overview/) are developed. Parcels are framework-agnostic components that can be seamlessly integrated as standalone features into any web application. They're constructed using React and compiled into web components, making them universally deployable. For mobile applications, the Abyss monorepo includes a `mobile` product. This product is designed to be used with React Native, allowing you to build cross-platform mobile applications using the same codebase. ```txt └── products ├── api | ├── .abyss │ | ├── environments.json │ | └── settings.json │ ├── src │ | ├── routes | │ | ├── graphql │ | | | ├── schema │ | | | ├── index.ts │ | | | └── resolvers.ts │ | | ├── index.ts │ | | └── routes.ts │ | ├── services │ | └── server.ts | └── package.json ├── mobile | ├── android | ├── ios | ├── App.tsx | ├── index.js | └── package.json ├── web | ├── .abyss | | ├── environments.json | | └── settings.json | ├── src | | ├── common | | ├── routes | | | ├── index.ts | | | └── Routes.tsx | | ├── browser.tsx | | └── document.tsx | └── package.json └── workshop ├── .abyss | ├── environments.json | └── settings.json ├── src | ├── common | ├── parcels | | ├── ReactLogo | | | ├── index.ts | | | ├── ParcelApp.tsx | | └─────└── ParcelApp.stories.tsx | ├── decorator.tsx └── package.json ``` ### Removing products While the default template application includes these four products, you can remove any of them if they are not needed for your application. To do this, simply delete the corresponding directory from the `products` folder. For example, if you want to remove the `mobile/` product, delete the `products/mobile/` directory. This will have no impact on the other products in the monorepo, allowing you to customize your application to fit your specific needs. --- id: installation title: Installation --- ## Create an app Now, let's get started! Run the following command to create a new Abyss application using the `create-abyss-app` CLI tool: ```bash npx create-abyss-app my-new-app ``` ## Run Abyss Navigate into the **my-new-app** project directory and run the `web` product using the following commands: ```bash cd my-new-app npm run web ``` Once you see the screen shown below, you are now up and running with Abyss! ```jsx render const Home = () => { return ( Welcome to Abyss ); }; render(() => { return ; }); ```
Great job, your Abyss app is running! Looking to learn more? Checkout our other [Abyss tutorials](/web/developers/tutorials/intro/). These are **exclusive** to projects created using the `create-abyss-app` tool. --- id: running title: Running --- ## Running an Abyss application ** Note: [Abyss App Starter-Kit](/web/developers/abyss-app/installation/) Only ** ### Local development To run an Abyss application locally, use the following command: ```bash npm run dev ``` This command starts the local development server an run all three products in the starter app: - `web` runs on `localhost:3000` - `api` runs on `localhost:4000` - `workshop` ([Parcels](/foundations/parcels/overview/)) runs on `localhost:5000` To run each product separately, you can use the following commands: - For the `web` product: ```bash npm run web ``` - For the `api` product: ```bash npm run api ``` - For the `workshop` product: ```bash npm run workshop ``` **Note:** The `npm run dev` command should _not_ be used to run the application in production. It is intended for local development only and includes features like hot module replacement, which are not suitable for production environments. ### Web #### Production build To build the Abyss web application for production, use the following command in the `products/web` directory: ```bash npm run build ``` This command compiles the application into an optimized build that can be deployed to a production environment. To learn more about the possible configuration options for the production build, see our [Abyss configuration docs](/foundations/configuration/web/web-settings/). The build can be run locally using the following command in the `products/web` directory: ```bash npm run preview ``` This runs the production build locally on the same port as listed above. #### Running in production How you run the Abyss application in production depends on the application's build type. By default, Abyss applications are built as Next.js applications (`"buildType": "browser-node"`), which can be run by executing the `build/server.js` file. For example: ```bash node server.js ``` This command starts the Next.js server, which serves the application in production mode. Ensure that you have set the [environment variables](/web/developers/abyss-app/environments) and configurations required for production before running this command. When using `"buildType": "browser-static"`, the application is built as a static site. In this case, there will be a version for each environment in the `build/` directory. You can serve the `index.html` file however you'd like. ### API #### Production build To build the Abyss API application for production, use the following command in the `products/api` directory: ```bash npm run build ``` This command compiles the API application into an optimized build that can be deployed to a production environment. #### Running in production To run the Abyss API application in production, execute the `build/server.js` file. For example: ```bash node server.js ``` ### Workshop (Parcels) To learn more about Abyss Parcels, see our [Parcels documentation](/foundations/parcels/overview/). --- id: upgrading title: Upgrading --- ## Upgrading Abyss Abyss releases [New Versions](/web/releases/) on a biweekly basis. For further details, refer to our [Versioning Guide](/web/developers/migration/versioning-guide/). Benefits to staying current with the latest version of Abyss include: - **Adhering to Brand Guidelines** - Align with the latest branding guidelines, ensuring your application maintains a consistent look and feel with the overall brand identity. - **Enhanced Security** - Address vulnerabilities and security enhancements to protect your application against emerging threats. - **Improved Accessibility** - As accessibility standards evolve, Abyss updates provide enhancements and fixes that help ensure your application is accessible to all users, including those with disabilities. - **Access to New Components Features** - Gain access to new components and features that can enrich the user experience and offer new functionality for your application. - **Bug Fixes** - Addresses defects that improve the stability and performance of your application. - **Efficient Upgrades and Minimal Regression Testing** - Staying updated with the latest version simplifies the upgrade process and minimizes related regression testing efforts. ## How to upgrade Abyss You can upgrade Abyss by running the following command in the root of your directory. ** Note: ** This command will update all Abyss packages to their latest versions. ```bash npm run upgrade ``` --- id: environments title: Environments --- ## Overview ** Note: [Abyss App Starter-Kit](/web/developers/abyss-app/installation/) Only ** Environments allow us to create different workspaces to develop our applications in. Each of these workspaces may require different variables depending on what stage of the development lifecycle they are in. To accomplish this Abyss utilizes a environments config file called `environments.json` under the `.abyss` config directory. ```txt ├── .abyss | ├── environments.json | └── settings.json ``` ## Abyss configuration The `environments.json` file is setup to help you designate your various environments including their desired name and associated variables. Below is a standard setup for the environment config. ```json { "env": { // Global variables "APP_NAME": "Create Abyss App - Micro Frontend" }, "env.dev": { // Env specific variables "ENV_VAR": "dev-only" }, "env.test": { "ENV_VAR": "test-only" }, "env.stage": { "ENV_VAR": "stage-only" }, "env.prod": { "ENV_VAR": "prod-only" } } ``` The `env` field allows you to define global variables that are applied to all environments. Environment variable names should follow the snake case standard. To create a new environment you must first define the environment with `env.` followed by the name you wish to give the environment (i.e `"env.prod"`). Once defined, anything you add to the field can be accessed by that environment only. ## Local You may also need to have environment variables when you are running and developing your application locally. To accomplish this you can add the common `.env` file to the root of your project. Anything you add to this file can be accessed when running your application locally. ```txt # Environment variables. STATUS=production API_KEY=secret # Development port DEV_PORT=7000 ``` ## Abyss config tool You can leverage the Abyss `config()` method to access both your `.env` and `environments.json` configurations inside your application. To learn more head to the [config](/web/tools/config) documentation. --- id: eslint title: Eslint --- ## Overview ** Note: [Abyss App Starter-Kit](/web/developers/abyss-app/installation/) Only ** Abyss has built-in lint tooling that is set up to help you maintain a consistent code style across your project. The configuration is very minimal and it is _recommended_ that for teams looking for more advanced linting to utilize their own ESLint configuration. CLI examples of running the Linter: - `npm run lint -- --fix` from the `web` directory. - `npm run lint` from the `root` directory _(runs across all products, i.e. web, api, parcels/workshop)_. ### Supported options - `--fix` - Uses the eslint fix option to fix as many issues as possible. - `--ci` - Will trigger a process exit 1 whenever any lint errors are found. - `--format` - Uses the eslint format option to specify the output format for the console (defaults to usage of eslint-formatter.js) **Important:** Teams requiring more advanced linting should implement their own ESLint configurations rather than requesting additional features. If you'd like to utilize any Eslint CLI options beyond the [supported options](#supported-options) listed above, please run the `eslint` command directly rather than using `abyss lint`. ## Migrating ** Please note that this is only applicable for teams that created an abyss app project prior to version `1.61.0`**. Due to ESLint 7 being EOL and the need to upgrade to ESLint 9, we have made the necessary changes to the linting configuration. **Step 1:** Make sure you're upgraded to Abyss core version `1.61.0` or above. - All versions below `1.61.0` can continue to use the existing linting configuration. **Step 2:** Update your `eslint` package to the latest version in your root `package.json`. ```json "eslint": "^9.15.0", ``` **Step 3:** Remove `eslintConfig` from your `package.json` inside the `web`, `api` and `parcels`/`workshop` directories. **Step 4:** Create a `eslint.config.js` file in the root of your project and add the following configuration: ```json module.exports = require('@uhg-abyss/core/eslint-config'); ``` **Step 5:** Remove the `.eslintignore` file from the root directory. **Step 6:** If present, remove the following from your `.vscode/settings.json` file: ```json "eslint.options": { "resolvePluginsRelativeTo": "node_modules/@uhg-abyss/core" } ``` **Note:** Teams should upgrade to `"typescript": "4.9.4",` in their root `package.json` to ensure compatibility with the latest ESLint configuration. --- id: code-connect title: Code Connect --- ## Figma Code Connect for Web Figma Code Connect is a Design-to-Code tool that aims to scaffold out the code required to implement a Figma Design. **Note:** Code Connect is currently in alpha and availability for components is changing. We invite you to discuss any enhancements or limitations in our Github Discussion Topic. **Note:** Only available for V2 components. ## Instructions This Demo Video contains an overview of how to use Abyss with Code Connect. - Open the Figma file with the component you want to use and select the component. In dev mode, the Code Connect will be viewable in the side bar under "Recommended Code". - The button "Explore component behavior" will allow you to see the component in a preview mode. You can change available props and variants from this panel. _Due to Figma limitations, not all possible combinations will be available through here. Check Abyss documentation._ ```jsx render Code Connect Example with Badge

``` #### Slot limitations At this time, code connect does not support slots. If you need to use a slot, you will need to manually add it to the code after copying it from Code Connect. The reccomended code section does not show the actual slot element's code. ```jsx render Code Connect Example with Slots

``` ### Supported components ```jsx render ``` --- id: abyss-admirals title: Abyss Admirals pagination_prev: null isHidden: true --- ## Who are Abyss Admirals?

An Abyss Admiral is a highly specialized role for a software engineer who is a dedicated member of a product delivery team. The most basic and essential function of an Admiral is to act as a bridge between the core Abyss ecosystem and the product team leveraging the framework.

Acting as representatives or ambassadors for their products, Admirals enable the adoption of a{' '} scalable, federated software development model by sharing the Abyss community's best practices with their teams. As subject matter experts for Abyss, Admirals are encouraged to guide and mentor their engineering teams, empowering them to take advantage of the benefits of working in a collaborative enterprise environment.

## Benefits for Product Stakeholders It's very important for product stakeholders to understand that an Admiral's involvement in their new responsibilities will reduce their capacity for delivering sprint work as a standard individual contributor. However, by allocating enough time for the role, Admirals will enable engineering scrum teams to measurably improve both quality and delivery metrics. It's recommended to dedicate between **30% - 50%** of an Admiral's capacity for this role, but could be up to 100% depending on the size and scope of the project. Product stakeholders will be able to capitalize on the efficiencies gained by leveraging the collective knowledge and shared solutions that are accessible through the broader Abyss community. The benefits of staffing a dedicated Admiral on your product include: - **Accelerated Solution Development:** When delivery teams are asked to identify and create solutions to common problems, they’ll need to do so in between developing new features which can result in delays. An Admiral assists their product teams at critical moments by eliminating these bottlenecks and offering proven solutions, which in turn increases the speed of delivery.

- **Minimized Duplication of Work:** The Abyss team facilitates the creation of reusable digital assets such that, when the business makes a new request, an Admiral can utilize a similar solution that was built previously for another team rather than building a new one from scratch, greatly minimizing cost and time to value.

- **Consistent Product Quality:** It’s reasonable to assume that most teams will not be evenly balanced when it comes to experience and skill levels, resulting in products being built with different techniques and standards. Admirals can ensure that the quality of development is both consistent and in accordance with the established standards of other products built with Abyss.

- **Expansive Specialist Network:** When working with an Abyss Admiral, product stakeholders obtain access to a network of highly experienced and qualified specialists including software architects, lead engineers, UX designers, accessibility experts who are motivated to craft the best product experiences possible. ## Benefits for Engineering Managers It's very important for engineering managers to understand that an Admiral's involvement in their new responsibilities will reduce their capacity for delivering sprint work as a standard individual contributor. However, by allocating enough time for the role, Admirals will enable engineering scrum teams to measurably improve both quality and delivery metrics. It's recommended to dedicate between **30% - 50%** of an Admiral's capacity for this role, but could be up to 100% depending on the size and scope of the project. Engineering managers will be able to capitalize on the efficiencies gained by leveraging the collective knowledge and shared solutions that are accessible through the broader Abyss community. The benefits of staffing a dedicated Admiral on your delivery team include: - **Reduced Software Fragmentation:** When individual teams are developing within disconnected, siloed environments, they’ll often discover multiple different approaches to solve the same problem. Admirals can act as advisors to prevent this additional overhead from occuring by raising awareness of pre-existing solutions.

- **Promote Engineering Growth:** For an engineer who is eager to progress further along their career path, the Admirals program offers an elevated set of responsibilities for overseeing software projects. Since this role is both highly technical and relationship-oriented, coupled with a sense of personal accountability, Admirals can leverage this experience to explore their interest in management or technology leadership roles.

- **Accountability for Essential Tasks:** Engineering teams are often overburdened with upkeep and maintenance related chores because they are given a lower priority than feature work. By assigning an Admiral to each project, engineering managers can verify that code quality, versioning, and peer review processes are being observed.

- **Optimized Outcomes:** Admirals reduce the time and cost of development through specialization and economies of scale. By tapping into a centralized community of knowledge, skills, and experience, the Admirals program is able to streamline access to those scarce capabilities while also facilitating balanced, cohesive engineering teams. ## Admiral Assignments - **Upgrade Abyss Versions:** It's highly beneficial to keep your product up-to-date with the newest versions of Abyss. Inform your engineering team and product stakeholders of any new components, tools, or patterns your application can leverage. - **Review the [release notes](/web/releases/) after a release** to determine the level of effort for upgrading to the latest version. - **Run the command "npm run abyss"** to automatically upgrade all Abyss packages in your project. - **Support for new features and defects** will only be included in new versions.

- **Monitor Code Quality:** As an Admiral, the accountability of maintaining high standards for code quality starts with you. Become well-versed in JavaScript, React, ESLint, and SonarQube anti-patterns and shepherd your team away from these pitfalls, reducing the burden of unrestrained technical debt and extending the lifespan of your codebase. - **Remediate runtime errors & warnings** observed in the browser's developer console for your product. - **Inspect problems reported by [ESLint](https://eslint.org/docs/latest/rules)** and discuss rule modifications with other Admirals. - **Triage issues identified by [Sonar](https://sonar.optum.com)** to ensure your product meets code quality benchmarks.

- **Manage Pull Requests:** Within the GitHub repository for your product, you should encourage your team to open pull requests regularly. By consulting with other Admirals, you are in the most well-suited position to act as a code reviewer for your team. - **Open draft PR's early** in the sprint to give you and your team enough time to review and offer feedback on the approach. - **Offer comments and conduct reviews** for each PR before approving. - **Merge PR's in a timely manner** to improve time-to-build metrics for your product.

- **Leverage Assets:** Admirals should strive to identify all of the usuable assets that exist within Abyss, as well as the network of individuals involved. Becoming familiar with the abstract concepts of a framework will elevate the engineering maturity of your team. - **Research code developed for Abyss** to understand the patterns for consistent, repeatable software practices. - **Review and update documentation** which demonstrates guidance for best practices, guidelines, and considerations. - **Foster relationships with key experts** who possess very specific and unique skill-sets who can influence the growth of your product.

- **Continous Learning:** To be successful, Admirals should provide thought leadership, direction, and appropriate recommendations for their teams and the Admiral community. The ability to both absorb and transfer knowledge is essential. - **Have a self-starter attitude** and a passion for growing your career by being surrounded by like-minded engineers. - **Seek opportunities for learning** by reading developer blogs, attending tech conferences, and networking with other Admirals. - **Familiarize yourself with industry trends** by researching and recommending techniques for application development.

- **Sustainable Software:** When left unchecked, the sustainability of an application can continuously deteriorate. Admirals are able to counteract this by taking appropriate measures to establish a healthy development environment and extend the lifespan of a product. - **Maintain a log of tech debt** and track the ongoing scope of maintenance tasks incurred from past sprints. - **Conduct frequent pair programming** sessions with your team to guide current feature development. - **Discuss upcoming requirements** with architects to establish a clear path for future stories in your product pipeline.

- **Abyss Contributions:** With the Admiral contribution process, the development process for new assets can be accelerated by building the solution yourself as the need arises; rather than waiting for your idea to reach the top of the Abyss core backlog. - **Determine the priority** for framework enhancements based on your product delivery schedule. - **Discuss new ideas in [Office Hours](#abyss-office-hours)** with the core team and other Admirals. - **Follow the [Contribution Workflow](#contribution-workflow)** shown below to share your proposals with the framework. ## Admiral Developers Guide If an existing Abyss component doesn't meet your product's requirements, you can follow this guide for building and testing changes within your application's codebase. Start by cloning the package structure of abyss within your product, such as **'src/abyss/web/ui/Badge'** demonstrated below. If you are creating a new component, you can start with a similar one as a template, otherwise cloning the existing component is the recommended approach. ```txt └── products └── web ├── .abyss ├── src | ├── abyss | | └── web | | └── ui | | └── Badge | | ├── index.js | | └── Badge.jsx | ├── common | ├── routes | ├── client.jsx | └── document.jsx └── package.json ``` Next, replace the relative imports with absolute paths to **@uhg-abyss/web**. You can use any combination of Abyss package imports, open source libraries, and custom JavaScript dependencies to build your component. ```jsx import React from 'react'; import PropTypes from 'prop-types'; import { styled } from '../../tools/styled'; import { useAbyssProps } from '../../hooks/useAbyssProps'; import { useVisuallyHidden } from '../../hooks/useVisuallyHidden'; ``` Replace with: ```jsx import React from 'react'; import PropTypes from 'prop-types'; import { styled } from '@uhg-abyss/web/tools/styled'; import { useAbyssProps } from '@uhg-abyss/web/hooks/useAbyssProps'; import { useVisuallyHidden } from '@uhg-abyss/web/hooks/useVisuallyHidden'; ``` Finally, to test your component changes, modify your import path by changing **'@uhg-abyss/web/ui/Badge'** to **'@src/abyss/web/ui/Badge'** which will use your local Abyss component. Once you have fully verified your changes, you can submit a new Pull Request back to [Abyss](https://github.com/uhc-tech/abyss/pulls) and showcase your updates in the Abyss office hours. Once merged, your contributions will be available in the next release! ## Contribution Workflow

As an Abyss Admiral the workflow for a contribution goes as follows: 1. Office Hours: Discuss proposal for new components, designs, architecture, and tools with other Admirals. 1. Abyss Contact us: If idea can be re-used, submit a new request with Abyss "Contact Us" form. 1. Develop Locally: Follow the steps in Admiral developers guide to create re-usable asset locally in your product. 1. Abyss GitHub: Before opening a new Pull Request, ensure that all requirements are met for UX, branding, and accessibility guidelines. 1. Abyss Office Hours: Demo proposed feature with Abyss core team and other Admirals. 1. Abyss Github: Pull Request undergoes modifications from feedback, acceptance, quality checks and merge. The contribution will end with the finalized abyss packages

![Contribution Workflow](/img/graphics/abyss_admirals_flowchart.png) ## Abyss Office Hours | Day | Time | Meeting | | -------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Tuesdays & Thursdays | 8:30 - 9:30 AM **CST** | [Join Teams Meeting](https://teams.microsoft.com/l/meetup-join/19%3ameeting_MTdkODUwYzQtZTNiZS00M2EyLWJmOTMtOGJjMTU4YTYyNWU5%40thread.v2/0?context=%7b%22Tid%22%3a%22db05faca-c82a-4b9d-b9c5-0f64b6755421%22%2c%22Oid%22%3a%22d5140f05-c25a-491a-8c4f-ad6da5e23bad%22%7d) | --- id: abyss-contributors title: Abyss Contributors --- ## Overview First of all, thank you for your interest in contributing to Abyss. All of your contributions are valuable to the project! There are several ways you can get involved in the Abyss community and become a contributor: - **Share Abyss:** Share the link to [Abyss](https://abyss.uhc.com) with members of your product team, and we'd be happy to discuss how we can help support your application. - **Improve documentation:** Help us improve the Abyss Docs by fixing incomplete or missing sections, examples, and explanations. - **Provide feedback:** The team at Abyss are constantly working to make the project better, please let us know what features you would like to see with the [Contact Us](/web/contact-us/) form. ## Abyss code repo ```jsx render () => { const customIcon = ( ); return (

The Abyss source code monorepo contains both core packages and products:

Packages:

api
core
desktop
ext
infra
mobile
parcels
utility
web

Products:

assets
docs
ext
scaffold
storybook

{customIcon} } > Visit ); }; ``` ### Setting up project locally For the essential system tools to get Abyss running on your local development environment, visit our [workplace setup](/web/developers/workplace-setup) guide. To set up, clone the abyss repository: ```bash # Make the abyss-projects directory mkdir abyss-projects && cd abyss-projects # Clone the abyss repository git clone https://github.com/uhc-tech/abyss.git ```
Afterwards, install the dependencies for `abyss` on your machine: ```bash # Go into the abyss directory cd abyss # Install abyss dependencies npm i ```
Then you are ready to start `abyss-docs` on your machine: ```bash npm run docs ``` ### Commit conventions Head to the Abyss source code for updates and additions to our Abyss NPM packages and documentation. With several contributors working in these repos daily, it's important to write your commit messages to be as descriptive as possible. Commit Convention: ``` [area] Optional title: Message ```
Examples: ``` [docs] Button: Edit accessibility section [@uhg-abyss/ui] useLoadingOverlay: Add remove handler [@uhg-abyss/core] Fix non-prod deployment scripts [@uhg-abyss/ui] Carousel: New feature added [docs] Doc scripts: Fix docs deployment script ``` ### Git branch names Naming the branch you're working on helps repository maintainers understand the changes being made when the PR is opened. Using consistent branch name prefixes also allows build tools to automatically categorize the branches using labels. Branch names should be all lowercase (with the exception of US and DE) and include hyphens between words. All branches are divided into four groups: - **story/#######** - Changes associated with a User Story, use the unique 7-digit number from Rally followed by a task description. - **defect/#######** - Changes associated with a Defect, use the unique 7-digit number from Rally followed by a task description. - **refactor/** - Changes to the repo that aren't documented in Rally are considered refactors, so use the task portion to add detail to your branch name. - **release/** - Used specifically by build tools, this branch name is exclusive to release notes and documentation leading up to a new release. Examples: ``` git checkout -b story/US2434515-developer-toolkit git checkout -b defect/DE308703-button-accessibility git checkout -b refactor/select-list-multi-docs git checkout -b story/US1533842-use-loading-overlay ```
Branch Name Rules: - Branch prefix must start with **story**, **defect**, **refactor**, or **release** - Branch name must be only **lowercase letters, numbers, and hypens** - **US###** and **DE###** are valid character exceptions ## Secure groups Visit secure.uhc.com to request permissions groups: - **abyss_contributors**: For write access to abyss code repositories ## Developer tools Abyss is built using a list of trusted resources. Below are links to what makes up the framework of Abyss. ```jsx render () => { const devLinks = [ { id: 1, name: 'ReactJS', href: 'https://reactjs.org/', }, { id: 2, name: 'Docusaurus', href: 'https://docusaurus.io/', }, { id: 3, name: 'Stitches', href: 'https://stitches.dev/', }, { id: 4, name: 'React Hook Form', href: 'https://react-hook-form.com/', }, { id: 5, name: 'React Router', href: 'https://reactrouter.com/', }, { id: 6, name: 'npm', href: 'https://docs.npmjs.com/about-npm', }, ]; return ( {devLinks.map((link) => { return ( } linkText={link.name} > {link.name} ); })} ); }; ``` If you're ready to get started with Abyss on your own, checkout the Abyss StarterKit (coming soon) to get started. ## Design tools Abyss has a dedicated team of designers creating a Design Kit on Figma. Below are some resources to help developers navigate these tools: ```jsx render () => { const designLinks = [ { id: 1, name: 'Abyss Design Kit', href: 'https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web?m=auto&node-id=0-367&t=myRGGrhQUPbwh0Zk-1', }, { id: 2, name: 'Figma for developers', href: 'https://www.figma.com/best-practices/tips-on-developer-handoff/an-overview-of-figma-for-developers/', }, { id: 3, name: 'UHC branding', href: 'https://brand.uhc.com/design-with-care', }, { id: 4, name: 'Optum branding', href: 'https://brand.optum.com/', }, ]; return ( {designLinks.map((link) => { return ( } > {link.name} ); })} ); }; ``` If you're a designer and want to dive deeper into the Abyss Design Kit, visit our Designer Getting Started (coming soon) page to learn more.
--- id: documentation-guide title: Documentation Guide --- ## Overview The documentation pages are organized under the **docs** directory shown below. When adding a new component, tool, or guide to Abyss Docs, create a new markdown.md file under the associated folder. ```txt abyss-docs-web └── docs ├── api └── web ├── brand ├── developers ├── hooks ├── overview ├── tools └── ui ``` ## Markdown structure Each markdown file should begin with the following metadata, as an example: ```md --- id: carousel category: Content title: Carousel description: Displays information through a series of slides. design: https://www.figma.com/file/tk08Md4NBBVUPNHQYthmqp/Abyss-Design-System?node-id=3578%3A23477 pagination_prev: web/ui/card pagination_next: web/ui/step-indicator --- ```
Every doc page is divided into three tabs: Overview, Integration and Accessibility. Within the body of the markdown file, use these tabs to group sections of information. ``` **Overview Content** **Integration Content** **Accesibility Content** ```
## Overview Tab ###### Import statement Add the import statement for the feature like such: ```jsx import { Alert } from '@uhg-abyss/web/ui/Alert'; ``` ###### Component Sandbox Add Sandbox after the import statement for any components that make sense to have a sandbox. Inputs are controlled props that can be adjusted by the user using the Sandbox features. Organize the inputs alphabetically when possible, starting with the simple properties first. Each input contains `prop`, `type` and optionally: `options` and, `defaultValue`. To create a Sandbox, use the convention below: ```` ```jsx sandbox { component: 'Alert', inputs: [ { prop: 'title', type: 'string', }, { prop: 'children', type: 'string', }, { prop: 'inlineText', type: 'string', }, { prop: 'variant', type: 'select', options: [ { label: 'error', value: 'error' }, { label: 'success', value: 'success' }, { label: 'info', value: 'info' }, { label: 'warning', value: 'warning' }, ], }, { prop: 'hideIcon', type: 'boolean', defaultValue: 'false', }, ] } Alert Sandbox Content ```` ###### Property examples Following the Sandbox, it's important to show the ability of each property separate of the others. We break each one down, giving it a title, description and jsx example showing variants of that specific property. For example, if you wanted to show the three sizes for Button, you'd write: ``` ```
Since there are two visual variants of Button, `primary` and `outline`, which use the same sizing convention (`$sm`, `$md`, `$lg`) we can combine the two visuals under the one size example by organizing them utilizing the built-in Layout component from the Abyss library. Here's what the combined example looks like: ``` ```
To follow the complexity of each prop example, use the following rules to properly document the feature: - **When organizing the list of examples,** they should be ordered from simple to complex starting with size or width - **Start each example case** with "Use the `prop-name` property to..." followed by an explanation - **For props with a pre-set list of variants,** add a sentence listing out the variant options "Variants include `variant-1`, `variant-2`", and so on - **For props with a default value,** add "The default value is set to `value`" - **For the customization example section,** include the sentence “If further customization is needed, most styles of `component-name` can be overridden using `css`” - **Size and width examples** should include the list of Abyss style sizes (including the conversion of size to units in the label/text like $md = 16px), followed by percent, and px - **Examples may include:** size, width, isDisabled, controlled, uncontrolled, loading, and customization. Take a look at other doc pages for examples of how to best format the component you're documenting ## Integration Tab Implementing a props table and classes table for the component, and any sub-components gives users an in-depth view of the component without having to visit the code. (The below example is modified for this template. Please refer to the Alert component for a full list of props and classes). Follow these rules when creating a Props Table: - **Prop name** is lowercase - **Type** is one of the following: boolean, function, array, shape, number, string, number | string - **Default value** is the default value from the defaultProps list, or null - **Description** first word is uppercase, followed by a brief description of the props use Follow these rules when creating a Classes Table: - **Class name** starts with a period (.), is lowercase and uses dashes to separate words - **Description** first word is uppercase, followed by a brief description of the class #### Example of Integration Tab ```jsx render ``` ```jsx render ``` ## Accessibility Tab This tab is important to be as thorough and in-detail as possible, adhering to the WAI-ARIA design guidelines. Follow this pattern when creating the Accessibility tab: - **Brief description** write a description about the component, and link to the WAI-ARIA website page referring to the component - **Sandbox** allows our A11Y partners to practice assistive technology on the component in a dedicated field - **Keyboard interactions table** referring to the WAI-ARIA keyboard interactions, create a table with all interactions usable for the specific component - **Additional guidance** note any additional guidance features of the component, including (but not limited to) Decorative Icons, Loading State, etc. #### Example of Accessibility Tab An alert is an element that displays a brief, important message in a way that attracts the user's attention without interrupting the user's task. Dynamically rendered alerts are automatically announced by most screen readers, and in some operating systems, they may trigger an alert sound. It is important to note that, at this time, screen readers do not inform users of alerts that are present on the page before page load completes. Adheres to the Alert WAI-ARIA design pattern. ```jsx live {}} /> {}} /> {}} /> {}} /> ```
```jsx render ``` ###### Decorative Icons In the alert below, since the word “Warning” appears next to the icon, the icon is considered decorative and must be ignored by assistive technology. The icon does not need to meet the 3:1 minimum contrast requirement against its adjacent color. ```jsx live ``` ###### Close Button Guidance Keyboard operation: if the “close” button is used on the alert, it must be keyboard accessible. A keyboard only user must be able to tab to the button, and activate it with the space bar and the enter key. ```jsx live {}} /> ```
Note: per the WAI ARIA specification, when the “alert” role is used, the user should not be required to close the alert. In this case, it is assumed that the close button is provided as a convenience and the user is not explicitly required to close the alert. --- id: overview title: Overview --- This guide is designed to help teams seamlessly integrate Abyss into their existing applications, enhancing their development capabilities with our robust suite of tools and features. Whether you're looking to improve your app's scalability, performance, or developer experience, Abyss is the right choice to elevate your project. **Note:** The recommended way to get started with Abyss is by using `create-abyss-app`. Go to our [Create Abyss App Guide](/web/developers/abyss-app/overview/) to get started! --- id: installation title: Installation --- ## Peer dependencies Please note that react and react-dom are peer dependencies, meaning you should ensure they are installed before installing Abyss. ```jsx "peerDependencies": { "react": "^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "react-dom": "^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" }, ``` ## Install Abyss Web To add Abyss web to an existing application, first install the Abyss dependencies: ```jsx npm install @uhg-abyss/web ``` Then, wrap your application root component with [`ThemeProvider`](/web/ui/theme-provider). The `ThemeProvider` enables global theming for your application, with the option to customize or rely on the default styles of Abyss components. Utilizing React's context, it distributes your theme to all nested components. ```jsx import { ThemeProvider } from '@uhg-abyss/web/ui/ThemeProvider'; const theme = createTheme('uhc'); function Demo() { return ( ); } ``` ## Importing components Abyss documents give detailed directions for the importation and use of all components within the Abyss library. Simply seach Abyss docs for the component you would like to use and follow the guide. Below is an example of how to import the `Button` component into your file. ```jsx import { Button } from '@uhg-abyss/web/ui/Button'; ``` --- id: upgrading title: Upgrading --- ## Upgrading Abyss Abyss releases [New Versions](/web/releases/) on a biweekly basis. For further details, refer to our [Versioning Guide](/web/developers/migration/versioning-guide/). Benefits to staying current with the latest version of Abyss include: - **Adhering to Brand Guidelines** - Align with the latest branding guidelines, ensuring your application maintains a consistent look and feel with the overall brand identity. - **Enhanced Security** - Address vulnerabilities and security enhancements to protect your application against emerging threats. - **Improved Accessibility** - As accessibility standards evolve, Abyss updates provide enhancements and fixes that help ensure your application is accessible to all users, including those with disabilities. - **Access to New Components Features** - Gain access to new components and features that can enrich the user experience and offer new functionality for your application. - **Bug Fixes** - Addresses defects that improve the stability and performance of your application. - **Efficient Upgrades and Minimal Regression Testing** - Staying updated with the latest version simplifies the upgrade process and minimizes related regression testing efforts. ## How to upgrade Abyss You can upgrade Abyss by running the following command in the root of your application: ```bash npm install @uhg-abyss/web@latest ``` ```bash yarn add @uhg-abyss/web@latest ``` --- id: nextjs title: NextJS --- ## Recommendations for Abyss in Next 13+ If you are OK with only client-side rendering, put your pages under `/app`, and add the `"use client";` to those pages. This disables SSR and RSC streaming for those pages. \* If you require SSR for some or all pages, put those pages under `/pages`, where you can use the old SSR model. ## Abyss SSR support in NextJS | NextJS Version | /pages | /app | | -------------- | ------ | ----------- | | 12 | ✅ | N/A | | 13,14,15 | ✅ | Client-only | _\* Note: In some cases, the presence of the `"use client"` directive does NOT prevent the server from generating the HTML markup of the component! However, since the NextJS documentation contradicts this, your mileage may vary._ ## Background In NextJS versions 12 and lower, routes are defined under the `/pages` directory, and have options to render on the server (SSR), or on the client. SSR is one way to speed up a user's experience, by providing them HTML before loading and running JavaScript in the browser. In NextJS 13, an alternate way of speeding up requests was designed - React Server Components (RSC) - which allows the server to send its results bit-by-bit. This allows the faster parts of rendering server HTML to be seen by the user sooner, as parts of the page are streamed. This new behavior is the default for pages under `/app`. However, the streaming aspect of RSC limits what kind of functionality can be rendered and streamed. In particular, Context and Provider, can not be used, as shown in the error: > `Error: createContext only works in Client Components.` This happens because Abyss theming and other features are implemented using React Context - a practice which is recommended by the React team, and typical of 3rd party components. ### SSR lifecycle The lifecycle of a typical `/pages` SSR request is: - Page renders on the server, sending HTML to the browser - The browser downloads the JS chunks for the page - The browser executes the chunks, re-rendering the page in the 'hydration' process - When hydration is complete, the static markup is now under control of React, and the page will behave as a Single-Page App, or SPA. ## References - [NextJS: Server and Client Composition Patterns](https://nextjs.org/docs/app/building-your-application/rendering/composition-patterns) - [NextJS: App Router](https://nextjs.org/docs/app) - [Vercel: Context and server components](https://vercel.com/guides/react-context-state-management-nextjs) - [Reddit: Do context providers force all child components to use client rendering?](https://www.reddit.com/r/nextjs/comments/1442a6y/do_context_providers_force_all_child_components/) ## Sample applications A sample NextJS 14 app, with usage of `/pages` and `/app`, is located in the Abyss repo at the path: [`/products/abyss-nextjs-14`](https://github.com/uhc-tech/abyss/tree/main/products/abyss-nextjs-14) A sample NextJS 15 app, with usage of `/pages` and `/app`, is located in the Abyss repo at the path: [`/products/abyss-nextjs-15`](https://github.com/uhc-tech/abyss/tree/main/products/abyss-nextjs-15) Note: The NextJS 15 example uses React v19 and requires Abyss version 1.70.0 or higher. --- id: faq title: FAQ's --- ## Next.js app/page routing vs. react-router-dom in Abyss Starter Kit The Abyss Starter Kit will only support react-router-dom for the following reasons: - **Integration with Abyss Web Components**: Our Abyss UI components are intrinsically built around `react-router-dom`. Leveraging it would ensure seamless compatibility and potentially smoother development process, leveraging the full potential of the UI components we have crafted. - **Flexibility and Customization**: While next.js does offer a structured approach to routing, `react-router-dom` stands out in terms of the flexibility it offers. `react-router-dom` also includes compatibility with [Abyss Parcels](/foundations/parcels/overview/). - **Independence from Next.js**: Although next.js is a vibrant and continually evolving framework, it often undergoes frequent updates, requiring developers to constantly adapt and update their codebase to stay aligned with the latest versions. By using `react-router-dom`, you can maintain a stable codebase that isn’t affected by the frequent updates in next.js, hence saving time and resources in the long run. - **Focused Usage of Next.js**: In our starter kit, we have employed next.js primarily as a build tool rather than a foundational framework for the entire application. - **Community Support and Resources**: `react-router-dom` has a vast community and a wealth of resources available. Its wide adoption in the industry means that you can find a robust ecosystem of tools, tutorials, and community expertise to leverage during your development process. - **Limited Support for next.js**: It is important to note that we do not plan on extending support for next.js app or page routing in our future roadmap. Our developmental efforts and updates will be squarely focused on enhancing the capabilities and functionalities woven around `react-router-dom`. Hence, to ensure that you have the best support and resources available for your project in the long term, we recommend aligning with our core focus on `react-router-dom`. Check out our [Abyss Routing](/web/developers/routing) documentation for more details. ## Version Conflict: react-router-dom Sometimes you're application will have various versions of `react-router-dom`. If the version you are using elsewhere is higher than the version of Abyss you must override the version in Abyss via the root package.json. Add the following: ```json { ..., "overrides": { "@uhg-abyss/web": { "react-router-dom": "6.13.0" // Match the version used in your application } } } ``` Once you've added the override you will need to delete every node_module folder as well as the package-lock.json and run `npm install`. **Note: This will only work with version 6 of react-router-dom and it's minor versions** ## TypeError: Cannot read properties of undefined (reading 'default') at Object.interopDefault To address the changes made in the next.js framework you must update the files in the `pages` directory inside your application. See below: ```txt └── products └── web ├── .abyss ├── pages | ├── _app.js | ├── _document.js | └── index.js ├── src └── package.json ``` Update the following files with the updated exports: \_app.js ```jsx export { default } from '@uhg-abyss/core/next-app'; ``` \_document.js ```jsx export { document as default } from '../src/document'; ``` index.js ```jsx export { browser as default } from '../src/browser'; ``` ## Create React App - Uncaught TypeError: (0 , react.createStitches) is not a function at createStyled If you are seeing this error you are most likely running a create-react-app application. To fix this error we need to override the base react-scripts using a library called Craco. ** 1. ** Follow the getting started documentation - https://craco.js.org/docs/getting-started/ ** 2. ** Add a craco.config.js file to the root of your application and include the following: ```jsx module.exports = { webpack: { configure: (webpackConfig) => { const newConfig = webpackConfig; newConfig.module.rules[1].oneOf[4].test = /\.(js|mjs|cjs)$/; return newConfig; }, }, }; ``` --- id: ai-code-gen-how-to title: How to use AI to perform code generation "CodeGen" with Abyss sidebar_label: AI Code Generation searchSiteWide: true --- ## Design-to-Code ## Prompt-to-Code --- id: installation title: Installation --- There are two ways to go about installing Abyss - either by creating a new Abyss app or by adding Abyss to an existing application. ### Create Abyss App (recommended) The recommended way to get started with Abyss is by using `create-abyss-app`. Go to our [Create Abyss App Guide](/web/developers/abyss-app/overview/) to get started! #### Advantages - **Zero Configuration Setup** - All tools are already configured that are essential for React development. Tools like Webpack (for bundling your code) and Babel (for using modern JavaScript features). - **Easy To Use** - You can start developing and see those results immediately. - **Optimized Build Output** - Provides optimized production builds out of the box, including minification, concatenation, and efficient loading (e.g., code splitting). - **Community and Support:** - Many team are already using the `create-abyss-app`, it offers significant support, regular updates, and a large number of resources for troubleshooting. ### Existing application For teams that want to use Abyss web within an existing React framework (i.e. NextJs) or are unable to migrate their existing application to a create-abyss-app you can still use Abyss within your application. Learn more about adding Abyss to your [Existing application](/web/developers/existing-application/overview/). ## Upgrading Abyss Abyss releases [New Versions](/web/releases/) on a biweekly basis. For further details, refer to our [Versioning Guide](/web/developers/migration/versioning-guide/). Benefits to staying current with the latest version of Abyss include: - **Adhering to Brand Guidelines** - Align with the latest branding guidelines, ensuring your application maintains a consistent look and feel with the overall brand identity. - **Enhanced Security** - Address vulnerabilities and security enhancements to protect your application against emerging threats. - **Improved Accessibility** - As accessibility standards evolve, Abyss updates provide enhancements and fixes that help ensure your application is accessible to all users, including those with disabilities. - **Access to New Components Features** - Gain access to new components and features that can enrich the user experience and offer new functionality for your application. - **Bug Fixes** - Addresses defects that improve the stability and performance of your application. - **Efficient Upgrades and Minimal Regression Testing** - Staying updated with the latest version simplifies the upgrade process and minimizes related regression testing efforts. ### How to upgrade Abyss - [Create Abyss App Upgrade Guide](/web/developers/abyss-app/upgrading/) - [Existing Application Upgrade Guide](/web/developers/existing-application/upgrading/) --- id: version-1 title: Migrating From v1 to v2 pagination_prev: null isHidden: true --- This guide is intended for teams looking to upgrade from Abyss v1 to v2 of Abyss. Various components are now deprecated. ```jsx render () => { const columns = [ { name: 'Abyss V1.0', key: 'old' }, { name: 'Abyss V2.0', key: 'new' }, ]; const rows = [ { id: 1, old: 'ContentEditor', new: 'Deprecated', }, { id: 2, old: 'FormBuilder', new: 'Deprecated', }, ]; return ( ); }; ``` ## Lagoon ```jsx render () => { const columns = [ { name: 'Abyss V1.0', key: 'old' }, { name: 'Abyss V2.0', key: 'new' }, ]; const rows = [ { id: 1, old: 'LagoonProvider', new: 'Deprecated in Abyss / Refer to the Lagoon documentation for more details.', }, { id: 2, old: 'useLagoon', new: 'Deprecated in Abyss / Refer to the Lagoon documentation for more details.', }, { id: 3, old: 'LagoonForm', new: 'Deprecated in Abyss / Refer to the Lagoon documentation for more details.', }, ]; return (

); }; ``` --- id: v0-to-v1-guide title: V0 to V1 Guide pagination_prev: null --- This guide is intended for teams looking to upgrade from Abyss v0 to the latest release of Abyss. Among the changes are some major architectural changes and updates, including consolidated packages, a new foundational UHC theme, new hooks and components, Figma integration, an upgraded CSS styling tool, and refactored form inputs and validation. We have also improved accessibility compliance, upgraded our application router, and made many performance updates across all areas. When you install our newest package dependencies, you'll automatically be up to date with the latest version. Abyss takes care of maintaining a robust product development framework so your team can focus on shipping a better product faster. ## Version overview With Abyss v1.0, we have consolidated the primary areas of application development into three main NPM packages - `@uhg-abyss/web`, `@uhg-abyss/api`, and `@uhg-abyss/core`. - `@uhg-abyss/web` represents the client-side packages, React components, hooks, and tools. - `@uhg-abyss/api` represents the server-side packages, including the GraphQL server, Express middleware, and other libraries. - `@uhg-abyss/core` includes the configurations for ESLint and Babel, which have been consolidated along with the dev and build scripts. This package will be shared with both client and server projects built on Abyss. ```jsx render () => { const columns = [ { name: 'Legacy Abyss', key: 'old' }, { name: 'Abyss V1.0', key: 'new' }, ]; const rows = [ { id: 1, old: '@abyss/ui', new: '@uhg-abyss/api', }, { id: 2, old: '@abyss/ui', new: '@uhg-abyss/web', }, { id: 3, old: '@abyss/core', new: '@uhg-abyss/web', }, { id: 4, old: '@abyss/scripts', new: '@uhg-abyss/core', }, { id: 5, old: '@abyss/eslint-config', new: '@uhg-abyss/core', }, { id: 6, old: '@abyss/babel-preset', new: '@uhg-abyss/core', }, { id: 7, old: '@abyss/test', new: 'Deprecated', }, { id: 8, old: '@abyss/widgets', new: 'Deprecated', }, ]; return

; }; ``` ## Component changes Some common UI components have changed for consistency. Below is a table comparing noticeable differences from legacy versions of Abyss to Abyss v1. This is a non-exhaustive list, and components that are not included could likely have styling updates. Our Brand and Design teams have made strong headway to update our standards since v0. We recommend following theme defaults, but if it is necessary to maintain the exact same design for your product, external styling or theme overrides can be done. ```jsx render () => { const columns = [ { name: 'Legacy Abyss', key: 'old' }, { name: 'Abyss V1', key: 'new' }, ]; const rows = [ { id: 1, old: 'Alert, AlertBanner', new: 'Component Name: Alert. AlertBanner deprecated.', }, { id: 2, old: 'Button', new: 'Component Props: link variant is now tertiary, theme and width props are deprecated.', }, { id: 3, old: 'Card', new: 'Component Props: width prop deprecated, many new props and classes for increased flexibility and functionality.', }, { id: 4, old: 'ExternalLink', new: 'Component Name: Link', }, { id: 5, old: 'Flex', new: 'Component Props: No longer need to use classes Flex.Flex and Flex.Content. Alignment and behavior can simply be applied directly with props such as justify, alignContent, direction, etc.', }, { id: 6, old: 'Icon', new: 'Component Name: Icon, IconMaterial, IconBrand', }, { id: 7, old: 'Link', new: 'In some cases, Link components would be wrapped with a Button component, mostly for styling purposes. This is no longer needed, can simply create a Button component with a href prop. The Link component still exists.', }, { id: 8, old: 'MaterialIcon', new: 'Component Name: IconMaterial', }, { id: 9, old: 'Modal', new: 'Component Props: New title and footer props (can still use Modal.Footer), scrollableFocus. onRequestClose is now called onClose. Modal.Scroll and Modal.Actions deprecated classes.', }, { id: 10, old: 'MultiSelectList', new: 'Component Name: SelectInputMulti', }, { id: 11, old: 'RadioGroup', new: 'Component Props: Use label prop for the title.', }, { id: 12, old: 'SelectList', new: 'Component Name: SelectInput', }, { id: 13, old: 'Switch', new: 'Component Name: Router. For Switch, use class Router.Routes.', }, { id: 14, old: 'TextArea', new: 'Component Name: TextInputArea', }, { id: 15, old: 'Toggle', new: 'Component Name: ToggleSwitch', }, { id: 16, old: 'Tooltip', new: 'Component Name: Tooltip and Popover', }, ]; return

; }; ``` ## Components unavailable The following components are not available in v1.0. Those marked "To Be Implemented" will be part of upcoming releases. ```jsx render () => { const columns = [ { name: 'Legacy Abyss', key: 'old' }, { name: 'Abyss V1.0', key: 'new' }, ]; const rows = [ { id: 1, old: 'ErrorMessage', new: 'To Be Implemented', }, { id: 2, old: 'ReadMore', new: 'To Be Implemented', }, { id: 3, old: 'DataViz', new: 'To Be Implemented', }, { id: 4, old: 'FormControl', new: 'Deprecated', }, { id: 5, old: 'AppProvider', new: 'Deprecated', }, ]; return (

); }; ``` Various hooks are also now deprecated, particularly in relation to forms and styling. Hooks relating to Redux are no longer available. ```jsx render () => { const columns = [ { name: 'Legacy Abyss', key: 'old' }, { name: 'Abyss V1.0', key: 'new' }, ]; const rows = [ { id: 1, old: 'useField', new: 'Deprecated', }, { id: 2, old: 'useFormState', new: 'Deprecated', }, { id: 3, old: 'useAction', new: 'Deprecated', }, { id: 4, old: 'useSaga', new: 'Deprecated', }, { id: 5, old: 'useModel', new: 'Deprecated', }, { id: 6, old: 'useBounds', new: 'Deprecated', }, { id: 7, old: 'useBreakpoint', new: 'Deprecated', }, { id: 8, old: 'useColor', new: 'Deprecated', }, { id: 9, old: 'useSize', new: 'Deprecated', }, { id: 10, old: 'useStyles', new: 'Deprecated', }, ]; return (

); }; ``` ## Branding The Abyss Design System now supports branding at a foundational level, with complete UHC, UHG, and Optum themes. A theme is comprised of several core parts that create the building blocks of the design system. See the Brand section of our docsite for brand colors, fonts and typography settings, icon libraries, and several brand-associated logos. Simply by using Abyss as a launch point for your project, you will be fully aligned with all enterprise digital brand standards and assets, with no additional setup required. **Note:** - Enterprise Sans is replacing UHC Sans. It is mandatory that all current and future work be updated to use new Enterprise Sans. Upgrade your Abyss version to v1.52.0 or above to begin leveraging the new font. ## Design integration To help teams quickly build and adapt a beautiful user interface, we've streamlined design and development for the Abyss Design System. We’re excited to announce the addition of a dedicated design team implementing best practices on components and tools for the [Abyss Design System in Figma](https://www.figma.com/file/tk08Md4NBBVUPNHQYthmqp/Abyss-Design-System?node-id=0%3A1). With this addition, your entire product team has the power to make updates and adjustments with ease, utilizing both developer docs and design guidelines that now live in one place. On each docs page, simply press the “View Design” button in the header that links directly to the ADS in Figma. Even more so now, design and development collaboration provides an on-brand, elevated, cohesive experience. ## CSS/styling tools There are multiple approaches teams can take for styling. Styling can be supported inline with the `css` prop on components, which allows for targeting classes that we have mentioned in the integration tab of any docs page. While we do not explicitly support external stylesheets, teams who already use this approach can continue doing so by applying through a `className`. These style customizations are described further here: https://abyss.uhc.com/web/developers/theming-styling/. However, our own components are built using the [styled](https://abyss.uhc.com/web/tools/styled/) tool via Stitches. ### Stitches We have updated our CSS-in-JS library from Styled Components to [Stitches](https://stitches.dev/). CSS-in-JS libraries have significant advantages over traditional CSS strategies by leveraging reusable variables, functions, and static code analysis. The Stitches API shares many similarities with Styled Components; however, only object literal syntax is supported. The main benefit of Stitches over all other React CSS strategies is that nearly all CSS is generated at build time rather than runtime. This avoids unnecessary prop interpolations during the render phase, which can add up quickly when building large applications with a dynamic, theme-driven design system. For detailed examples, review the docs for [@uhg-abyss/web/tools/styled](https://abyss.uhc.com/web/tools/styled/). To see a full migration guide, please read [migrating from Styled Components to Stitches](https://stitches.dev/blog/migrating-from-styled-components-to-stitches). **Note:** - In a future release of Abyss, we will be switching from Stitches to [Emotion](https://emotion.sh/docs/introduction). ## Routing We base our routing off of `react-router-dom`. Check out their [migration guide](https://reactrouter.com/en/main/upgrading/v5) from v5 to v6, or our own [routing overview](https://abyss.uhc.com/web/developers/routing/). - router.push() should now be router.navigate() - If deploying on AWS look at this [stack overflow post](https://stackoverflow.com/questions/51218979/react-router-doesnt-work-in-aws-s3-bucket) with deployment issues with routing - Use the baseRoute in `.abyss/settings.json` if needed ```json "baseRoute": "/YOURBASEPATH" ``` ## State management Redux is no longer built into any of our products. It can still be used alongside our products by any consuming team, but we also recommend using [Zustand](https://docs.pmnd.rs/zustand/getting-started/introduction). See our own guide at https://abyss.uhc.com/web/tools/create-store/. ## Forms fefactor Our new forms integration is entirely built on top of the [react-hook-form](https://react-hook-form.com/docs/useform) library. We have upgraded from the previous Redux implementation to a new [FormProvider](https://abyss.uhc.com/web/ui/form-provider/), which allows child form inputs to consume the form context and methods returned from the upgraded [useForm hook](https://abyss.uhc.com/web/hooks/use-form/). With the addition of useForm functionality, most of our hooks for form management have now been deprecated. This means form components and their state management could be a large portion of a team's migration efforts. We have not only expanded the collection of form inputs that are supported, but we have also consulted with accessibility experts to create first-class [WCAG](https://www.w3.org/WAI/standards-guidelines/wcag/) compliant interactions. ## Build Teams that are using AWS will need to use `browser-static` in `.abyss/settings.json`: ```json "buildType": "browser-static". ``` This is instead of the default `browser-node`. ## Abyss Scripts migration guide This guide is to help migrate from the old `@abyss/scripts` package to the new `@uhg-abyss/core` package. If a team is looking to use Parcels, see [our guides](https://abyss.uhc.com/foundations/parcels/overview/) for additional information. It is recommended to integrate Parcels by using Path One. ### Path one (recommended) Lift and shift the application into a new `create-abyss-app` (Recommended) - This will provide a more up-to-date foundation that will improve development and compatibility in the long run. - You can leverage additional Abyss tools like API and Parcels. --- **1.** Create a new Abyss application - Follow the [Getting Started instructions](/web/developers/abyss-app/installation/) to scaffold a new project. **2.** Bring over the old codebase - When bringing over the code, start small and fix errors as they appear. **3.** Migrate imports from `@abyss/ui` web components to `@uhg-abyss/web` components - You can still use the old `@abyss/ui`, but you may encounter issues. (Support for `@abyss/ui` has ended) - When installing the old `@abyss/ui`, you must force installation due to React version conflicts. **Notes:** - `@uhg-abyss/web` only supports `react-router-dom` v6. - `@uhg-abyss/web` does not support Redux. - Use Zustand instead: [https://abyss.uhc.com/web/tools/create-store/](https://abyss.uhc.com/web/tools/create-store/) ### Path two Migrate `@abyss/scripts` to `@uhg-abyss/core` - This option will keep you on an outdated tech stack. --- **1.** Install packages - `npm install @uhg-abyss/core` - `npm install typescript` **2.** Remove unused `@abyss` packages: - `@abyss/babel-preset` - `@abyss/eslint-config` - `@abyss/scripts` **3.** Add `prettier`, `eslintConfig`, and `bundleDependencies` configs to `package.json` (You may have to update paths): - [https://github.com/uhc-tech/abyss-app/blob/main/products/web/package.json#L5C2-L8](https://github.com/uhc-tech/abyss-app/blob/main/products/web/package.json#L5C2-L8) - [https://github.com/uhc-tech/abyss-app/blob/main/products/web/package.json#L23-L25](https://github.com/uhc-tech/abyss-app/blob/main/products/web/package.json#L23-L25) **4.** Add `tsconfig.json` file to the web app root (You may have to update the `"include"` path or add additional configurations): - [https://github.com/uhc-tech/abyss-app/blob/main/products/web/tsconfig.json](https://github.com/uhc-tech/abyss-app/blob/main/products/web/tsconfig.json) **5.** Add `next.config.js` file to the web app root: - [https://github.com/uhc-tech/abyss-app/blob/main/products/web/next.config.js](https://github.com/uhc-tech/abyss-app/blob/main/products/web/next.config.js) **6.** Add the `pages/` directory to the web root: - [https://github.com/uhc-tech/abyss-app/tree/main/products/web/pages](https://github.com/uhc-tech/abyss-app/tree/main/products/web/pages) **7.** Add the `.abyss/` directory to the web root: - [https://github.com/uhc-tech/abyss-app/tree/main/products/web/.abyss](https://github.com/uhc-tech/abyss-app/tree/main/products/web/.abyss) - You can add environment variables to the `.environments.json` file: [https://abyss.uhc.com/web/developers/environments/](https://abyss.uhc.com/web/developers/environments/) ## Future steps Now that your application/product has completed the migration to V1, here are next steps for planning and executing version updates to keep your product current and leverage new functionality released by Abyss. For more information on Abyss' release strategy, review our [Versioning Guide](https://abyss.uhc.com/web/developers/versioning-guide/). Abyss deploys biweekly minor version releases to improve our products and address any defects. It is recommended to keep up with the latest release of Abyss for the best experience. - `npm i @uhg-abyss/web@latest` to upgrade to the latest release - `npm i @uhg-abyss/web@1.XX.X` to upgrade to a specific version of Abyss --- id: v2-prepping-guide title: Prepping for V2 --- ```jsx render ``` ## Prepping for V2 of Abyss This is a prepping guide for ways teams can prepare for the upgrade from Abyss V1 to V2 before V2 is officially released. **What is the difference between a prepping guide and a migration guide?** This prepping guide is different from the migration guide that will be released with Abyss V2. Understanding these differences will help you plan your approach: | Prepping Guide (Current) | Migration Guide (Future) | | ----------------------------------------------- | ------------------------------------------------------------ | | Available **before** V2 release | Will be available **after** V2 release | | Focuses on **gradual preparation** | Provides comprehensive instructions for full migration to V2 | | Helps distribute workload across sprints | Will be a one-time migration effort | | Identifies components to start replacing now | | | Allows teams to adopt V2 patterns incrementally | | | **Reduces** migration complexity later | |
By following this prepping guide now, you'll significantly reduce the effort required when the full migration guide is released with Abyss V2. ## Dependencies ### React peer dependencies In Abyss V2, we are updating our peer dependencies for React and React DOM. The supported versions are changing: ```jsx // from: - "react": "^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" - "react-dom": "^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" // to: + "react": "^18.0.0 || ^19.0.0" + "react-dom": "^18.0.0 || ^19.0.0" ``` This means that **React 16 and 17 will no longer be supported** in Abyss V2. You should ensure your application is running on React 18 or 19 before migrating to Abyss V2. ## CSS styling - Emotion In Abyss V2, we're replacing `Stitches` with `Emotion` for our CSS-in-JS solution. Both libraries have similar APIs, so most applications won't be significantly affected, but some breaking changes are possible depending on your current usage. **Why are we migrating to Emotion?** - Stitches is no longer actively maintained, and we want to use a library that is actively supported and has a strong community. - Abyss/mobile has already migrated to Emotion, and we want to maintain consistency across our products. - Emotion provides better performance and a more flexible API for our use cases. - Emotion has better support for server-side rendering, which is important for our applications. - Shadow DOM support To read more please refer to our [ADR](https://github.com/uhc-tech/abyss/blob/main/products/abyss-docs-web/docs/adrs/decisions/adr-013-stitches-replacement.md). To prepare for this change we have given teams the following npm package `"@uhg-abyss/web": "N/A-emotion".` that the only difference is that it uses `Emotion` instead of `Stitches` for the styling engine. This will be our default styling solution in Abyss V2, so you should start using this package in your application **now** to prepare for the migration. ## Components With the migration to Abyss V2 we are making several changes to our components. This includes: - **Prop changes**: Some props have been removed, modified, or renamed. - **Component deprecations**: Some components will be deprecated and replaced with new ones. - **Component breaking changes**: Some components will have breaking changes that may affect how they are used in your application. ### Deprecations Here is a list of tools/hooks/components that will no longer be available in Abyss V2: **Note:** This list is not exhaustive and may change as we finalize the migration.
Teams should start replacing these components with their new counterparts or alternative solutions **now**, rather than waiting for the V2 release. By proactively doing this now, you can: - Reduce the refactoring effort required when V2 is officially released - Migrate in smaller, more manageable increments - Identify and resolve integration issues earlier - Ensure a smoother and quicker transition to V2 To help identify these deprecated components in your codebase, we've created a [codemod detection tool](#detect-deprecated-imports---codemod) that scans your project for deprecated Abyss imports. See the [Detect deprecated imports - Codemod](#detect-deprecated-imports---codemod) section below for instructions on how to use this tool. ### Component breaking changes We've documented all component changes to help with migration planning. For details, see the [Component Changes](/web/developers/migration-v2/components/) section. Many V2 components are already available with a "V2" prefix (e.g., `V2Button`). Start using these now to ease migration. **Note:** When V2 is officially released, the "V2" prefix will be removed and these components will replace their V1 counterparts. For example, `V2Button` will become `Button`. :::tip AI-Powered Component Migration Need help with component migration? Use our [AI-Powered Migration Copilot](/web/developers/migration-v2/v2-prepping-guide/#ai-powered-migration-copilot) to help convert V1 components to their V2 equivalents with proper prop mapping. ::: **Why should I use the V2 components now?** - Familiarize yourself with the new APIs and features - Identify any potential issues or changes in behavior early - Ensure your codebase is ready for the V2 release without needing a complete overhaul - Many of these components were completely rewritten to improve performance, accessibility, and usability - These components have many added features and improvements that are not available in the V1 components (e.g., tokens, design improvements, etc.) **Note:** These V2 components may change before the official V2 release. However, they are stable for production use and can be safely integrated into your application. ## Codemods / AI tools Abyss will provide codemods to help with the migration process. These codemods will help reduce the amount of manual work required to update your codebase. **Note:** Since this is not the official migration guide, future codemods may not be available yet ### AI-Powered Migration Copilot To help with component migration, we provide an AI context package that works with tools like GitHub Copilot, ChatGPT, or other AI code assistants. This context enables the AI to understand V1 to V2 changes and provide accurate migration assistance. #### Using the Migration Copilot - [Download the this zip folder](/migration/ai-migration-context.zip) - Extract the zip to your project root directory: ``` your-project-root/ ├── abyss-migration-ai-context/ │ ├── ABYSS-MIGRATION-ASSISTANT.md | └── MigrationData.json ├── package.json └── src/ └── ... (your project files) ``` Add the context to your AI tool of choice (e.g., Copilot, ChatGPT, etc.) referencing the folder location. Next you can prompt the AI tool with questions like: ```bash Migrate this file from V1 to V2 of Abyss Migrate the `Button` component from V1 to V2 of Abyss ``` Here is an example showcasing migrating a file from V1 to V2 of Abyss using the AI tool: ```bash Migrate #file:HelloAbyss.tsx from V1 to V2 of Abyss ``` **Note:** This is the result after using the one prompt above. No additional prompts were needed to get the correct result ```jsx render AI Migration Example from V1 to V2 of Abyss

AI Migration Example from V1 to V2 of Abyss

``` ### Detect deprecated imports - Codemod To help with identifying deprecated components, we provide a script that scans your codebase for deprecated Abyss imports. This script will help you identify which components need to be replaced before migrating to v2. **Note:** Abyss imports show deprecation warnings. This tool is used scan your codebase for all deprecated imports at once. ```jsx render Deprecation warning example in code

``` #### How to use the script - [Download this zip folder](/migration/detect-deprecated-imports.zip) - Move the folder to your project root directory. The structure should look like this: ``` your-project-root/ ├── abyss-migration-tools/ │ ├── scan-imports.sh │ ├── detect-deprecated-imports.js | └── deprecated-imports.json ├── package.json └── src/ └── ... (your project files) ``` - Run the following commands to make the script executable and scan your codebase: ```bash # Make the script executable chmod +x abyss-migration-tools/scan-imports.sh # Run the script to scan your entire codebase ./abyss-migration-tools/scan-imports.sh # Or specify a specific directory to scan ./abyss-migration-tools/scan-imports.sh src/components ``` The script will scan your codebase for deprecated Abyss imports and report any findings. For example, running the script might show output like this: ```jsx render Codemod Scan Example for Deprecated Imports

Codemod Scan Example for Deprecated Imports

``` After identifying deprecated imports, refer to the [Deprecation Table](#component-deprecations) above for specific migration advice for each component or utility. For example, the table shows that `createStore` should be replaced with Zustand directly. --- id: v1-to-v2-guide title: V1 to V2 Guide isHidden: true --- ```jsx render ``` --- id: components title: Component Changes --- ```jsx render ``` ## Overview This guide focuses on breaking prop changes to be aware of when migrating from Abyss V1 to V2. These include: - Props that have been removed - Props whose behavior or typings have been updated - Props whose names have been changed but whose functionality remains the same. This guide does **not** cover: - New props added in V2, or - Additional features and enhancements. For complete documentation of all available props, including new features added, refer to each component's dedicated documentation page. :::tip AI-Powered Component Migration Need help with component migration? Use our [AI-powered migration tool](/web/developers/migration-v2/v2-prepping-guide/#ai-powered-migration-copilot) to help convert V1 components to their V2 equivalents with proper prop mapping. ::: ## Accordion ## Alert ## Avatar ## Badge ## Breadcrumbs ## Button ## Card ## Carousel ### Slide ## Checkbox ## CheckboxGroup ## Chip ## DateInput ## Drawer ## DropdownMenu ## FormProvider ## Fullscreen ## Indicator ## Link ## LoadingSpinner ## Modal ## NavMenuPrimitives ## NumberInput ## PageBodyIntro ## PageFooter ## PageHeaderPrimitives ## Pagination ### ResultCount ## Popover ## ProgressBar ## RadioGroup ## Rating ## RichTextEditor ## SearchInput ## SelectInput ## SelectInputMulti ## Skeleton ## Slider ## StepIndicator ## Tabs ## TextInput ## TextInputArea ## TimeInput ## Timeline ## Toast ## ToggleSwitch ## Tooltip --- id: overview title: Overview --- Abyss is a full-stack web application framework that enables you to build products faster and easier than ever. It features a comprehensive set of tools that weaves together the best parts of React and GraphQL. By taking common patterns and modularizing them into accessible and reusable packages, Abyss is designed to accelerate the development of production-ready React web applications. The framework handles all heavy lifting behind the scenes, allowing you to focus on core business logic specific to your product. Automated code quality tools analyze, identify, and correct errors in the code, giving developers real-time feedback and training to standardize programming styles. With improvements in project maintainability, scalability, and source code quality, Abyss aims to deliver the best overall development experience. Developers looking to use Abyss must have, or obtain access via Secure, to Artifactory (repo1.uhc.com) ## Advantages of Abyss - **Adhering to Brand Guidelines** - Align with the latest branding guidelines across Optum, UHG, and UHC. - **Deliver Faster** - Don't need to reinvent the wheel we got your UI covered! - **Improved Accessibility** - As accessibility standards evolve, Abyss follow the four principles of the WCAG Guidelines ## Learning React Just starting your journey with React? Abyss is a framework built on top of the popular React library. Visit the React Quick Start docs to learn most of what you ned to know to get started. ## Developer tools Abyss is built using a list of trusted resources. Below are links to the documentation for the tools that make up the framework of Abyss. ```jsx render () => { const devLinks = [ { id: 1, name: 'React', href: 'https://react.dev/', }, { id: 3, name: 'Stitches', href: 'https://stitches.dev/', }, { id: 4, name: 'React Hook Form', href: 'https://react-hook-form.com/', }, { id: 5, name: 'React Router', href: 'https://reactrouter.com/', }, { id: 6, name: 'npm ', href: 'https://docs.npmjs.com/about-npm', }, ]; return ( {devLinks.map((link) => { return ( } > {link.name} ); })} ); }; ``` ## Support If you're ready to get started with Abyss for your next project, check out our [Contact Us page](/web/contact-us). Submit a new support request and let us know how we can help your team. If you found Abyss to be helpful, please give us a star on GitHub! --- id: routing title: Routing --- ## Overview When developing with Abyss, we highly recommend utilizing React Router Dom to handle routing within your application. Many useful Abyss components, such as [Link](/web/ui/link) and [Breadcrumbs](/web/ui/breadcrumbs), are integrated seamlessly with version 6 and above of **react-router-dom**. You can find examples of how to establish routing within your application using our collection of Abyss routing components and tools in the following sections. Although it is technically possible to use NextJS page and app routing, this is not recommended for best results. ## Laying the foundation To start off, wrap the base of your application with the [RouterProvider](/web/ui/router-provider) to enable react-router navigation. Next up is generating a browser router which contains all the routes and enables client side routing for your web application. The Abyss **createRouter** tool can assist with this; import `createRouter` and provide it your `Routes` component which will hold all the individual routes for your application (more on this in the next section - [Creating Routes](#creating-routes)). `createRouter` will return a router that should then be passed into the `RouterProvider`. ```jsx import { RouterProvider } from '@uhg-abyss/web/ui/RouterProvider'; import { createRouter } from '@uhg-abyss/web/tools/createRouter'; const router = createRouter(Routes); export const App = ({ children }) => { return {children}; }; ``` - [Abyss - RouterProvider](/web/ui/router-provider) ## Creating routes Before using routes in an application, they need to be defined, which is typically done within a component name, **Routes**. Into this newly created Routes component, begin by importing the [Router](/web/ui/router) component along with any page components you want to associate with a particular route. Next, add a single instance of `Router.Routes`, then define individual routes using `Router.Route` (leverages react-router-dom Route). Whenever the URL changes, react-router will reference the `path` value defined within your `Router.Route` components to find a match. If a match is found, react-router will render the associated component within the `element` prop. ```jsx import React from 'react'; import { Router } from '@uhg-abyss/web/ui/Router'; import { Home } from './Home'; import { Albums } from './Album'; export const Routes = () => { return ( } /> } /> ); }; ``` - [Abyss - Router](/web/ui/router) - React Router DOM - Route ## Dynamic routing Dynamic segments are parts of the URL path that start with ":". When the route matches the URL, dynamic segments are parsed from it and provided as params to other router APIs. In this example, any values after "/album/:" in the URL will be supplied to `params.albumId`. More information on accessing these parameters can be found in the next section, [Routing with Parameters](#routing-with-parameters). ```jsx import React from 'react'; import { Router } from '@uhg-abyss/web/ui/Router'; import { Home } from './Home'; import { Albums } from './Album'; export const Routes = () => { return ( } /> } /> } /> ); }; ``` - React Router DOM - Dynamic Segments ## Routing with parameters To access route params you'll need to first import [useRouter](/web/hooks/use-router). **useRouter** provides several methods that allow users to manage and interact with routing and navigation, including [getRouteParams](/web/hooks/use-router#getrouteparams). When **getRouteParams** is called, it returns an object of key/value pairs of the dynamic params available from the current URL. ```jsx import React from 'react'; import { useRouter } from '@uhg-abyss/web/hooks/useRouter'; const Album = () => { const { getRouteParams } = useRouter(); const { albumId } = getRouteParams(); console.log(albumId); // "thriller" }; ``` - [Abyss - getRouteParams](/web/hooks/use-router#getrouteparams) - React Router DOM - Dynamic Segments ## Nested routing Nested routing couples segments of the URL to component hierarchy and data. In this example, we have a parent route with the path of "artist" wrapping two child routes, with a path of "albums" and "about". When the URL path matches "/artist/albums" or "/artist/about", the components associated with these child routes are rendered within the Artist component using `Router.Outlet` (leverages react-router-dom Outlet). ```jsx import React from 'react'; import { Router } from '@uhg-abyss/web/ui/Router'; import { Artist } from './Artist'; import { Albums } from './Albums'; import { About } from './About'; export const Routes = () => { return ( }> } /> } /> ); }; ``` Utilize `Router.Outlet` in order to render the components from the matching child routes. ```jsx import React from 'react'; import { Router } from '@uhg-abyss/web/ui/Router'; export const Artist = () => { return ( <>

Artist Page

// If the path matches "/artist/albums", the Albums component will be rendered; if it matches "/artist/about", the About component will be rendered. ); }; ``` - React Router DOM - Nested Routing - React Router DOM - Outlet ## Additional links - [Abyss RouterProvider](/web/ui/router-provider) - [Abyss Router](/web/ui/router) - [Abyss useRouter](/web/hooks/use-router) - [Abyss Developer Tutorials - Page Routing](/web/developers/tutorials/page-routing) - [React Router Documentation](https://reactrouter.com/en/main) - [React Router Tutorials](https://reactrouter.com/en/main/start/tutorial) --- id: quality-engineering title: Quality Engineering description: QE Testing Overview --- ## Dedication to quality ## Test plan ## Automation testing Automation testing of Abyss components is a top priority. Currently, our automation tests consist of the following: ### Web ### Mobile ### Unit testing ## Manual testing ## FAQ --- id: end-user-spec title: End User Specifications description: Abyss Spec tags: [browser, os, operating system, safari, chrome, edge, ios, andriod] --- ## Version requirements ## Testing and review ## How are these numbers calculated? ## Abyss Web ## Abyss Mobile

\* Last updated December 2023. To ensure this document is kept up to date and relevant, it should be revisited and revised with the latest metrics information on a set schedule, such as quarterly or bi-annually. --- id: component-testing title: Component Testing description: Guide on how to facilitate testing of Abyss components. --- ## data-testid To facilitate the usage of component testing libraries such as **React Testing Library** you have the option of adding a `data-testid` attribute to a component's corresponding elements. By passing `data-testid` in as a prop with a value of the desired string ID, this attribute will be appended to all component elements that include a unique Abyss class name. Please see the Integration tab and the Classes sub-heading for each component to determine which elements will receive this test ID. The resulting `data-testid` value will be a concatenated string that combines the value passed in with the prop and the element's unique class name. For example, the following code: ```jsx live () => { const form = useForm(); return ( ); }; ``` will render the following HTML: ```html

Input with Test ID

``` --- id: accessibility-testing title: Accessibility Testing --- export const links = { a11y: 'https://en.wiktionary.org/wiki/a11y', wcag: 'https://www.w3.org/WAI/intro/wcag', axeDevTools: 'https://www.deque.com/axe', chromeExtension: 'https://chromewebstore.google.com/detail/axe-devtools-web-accessib/lhdoppojpmngadmnindnejefpokejbdd', htmlValidator: 'https://validator.w3.org/nu/#textarea', wcagParsing: 'https://cdpn.io/pen/debug/VRZdGJ', }; ## Overview Web accessibility, also known as a11y, is the design and creation of websites that can be used by everyone. Accessibility support is necessary to allow assistive technology to interpret web pages. Abyss fully supports building accessible websites and follows the WCAG accessibility standards and guidelines. The list below are steps to take as a developer to ensure accessibility compliance. Please take a minute to read through the following testing resources and familiarize yourself with how to utilize them for best practices. ## Keyboard navigation Use only a keyboard to navigate the page. Don't use your mouse or touchbar at all to test this. See if you notice any keyboard traps or anything that seems difficult. Expected keyboard behavior for custom components is typically the following, but there are exceptions: - **Tab** to get into the component - Use **arrow keys** to navigate within the component - **Tab** to get out of the component ## Axe DevTools Axe DevTools enable developers to rapidly fix accessibility issues using built-in references and solution patterns without requiring deep knowledge of accessibility standards. Axe can be installed as a Chrome extension. On Mac, it can be installed directly from the Chrome App Store. On PC, you have to submit a AppStore request to install it. ## HTML validation For the HTML Validator, use the WCAG Parsing bookmarklet on top of it after submitting. To install the bookmarklet, drag the "WCAG parsing only" link at the top of the page to your browser bookmarks bar. ## Mac VoiceOver shortcuts - **On/off** Command + F5 (or go to System Preferences > Accessibility > VoiceOver) - **Mute/pause** Control - **VO** Control + Option - **Navigate focusable elements** tab - **Navigate all content** VO + arrow keys - **Quick nav on/off** press and hold left and right arrow keys at same time (This allows you to navigate all elements using just the left and right arrow keys without the VO keys.) - **Open Rotor** VO + U - **Close Rotor** Esc - **Navigate rotor menus** left and right arrow keys - **Navigate within existing rotor menu** up and down arrow keys If using a PC, request Secure access to NVDA. ## NPM packages Most NPM packages rely on axe-core. Set an impact level, and start with critical issues then work down. Remember to allow time to fix critical issues in the User Story. Otherwise, the product developers will get frustrated and learn to ignore the errors, which defeats the purpose and doesn't help anyone. ## Linting For linting rules, work with an a11y engineer to determine what to include. ## Summary Remember, the tools and processes mentioned above don't catch all a11y issues, but they serve as a great start to empowering the team to do some of your own testing. For further information, reach out to an a11y engineer! ## Accessibility tools If you're looking for an in-depth overview of what accessibility standards Abyss is working towards, visit our [Accessibility page](/web/accessibility). ```jsx render () => { const accessibilityLinks = [ { id: 1, name: 'WCAG 2.1', href: 'https://www.w3.org/WAI/WCAG21/Understanding/', }, { id: 2, name: 'Color Contrast Analyser (CCA)', href: 'https://webaim.org/resources/contrastchecker/', }, { id: 3, name: 'W3 Validator', href: 'https://validator.w3.org/favelets.html', }, { id: 4, name: 'Digital A11y', href: 'https://www.digitala11y.com/accessibility-bookmarklets-testing/', }, ]; return (

{accessibilityLinks.map((link) => { return ( } > {link.name} ); })}

); }; ``` --- id: sandbox title: Sandbox --- import { Button } from '@uhg-abyss/web/ui/Button'; The Sandbox page is stripped down to the essentials, without extra text or elements, for a clean coding experience. Click the button to go to the Sandbox page. --- id: theming-styling title: Theming/Styling description: Guide to theming and styling Abyss components. --- # Overview This document provides a high-level overview on how to apply theming and style customization to Abyss components. Each component/tool mentioned below has its own dedicated documentation page, which we encourage you to visit and explore to better understand the full capabilities. We do our best to support flexibility when applying style customizations to Abyss components but we do recommend utilizing the [Designer Toolkit](/web/designers/design-kit/#designer-toolkit) and keeping customizations to a minimum, as the Abyss components are designed to create a standard across all UHG affiliated products. ## Theming setup To ensure a consistent look and feel across your application and for proper styling customization to take effect, you must first set up theming in your application by using the `ThemeProvider` component and `createTheme` tool. ```jsx import { ThemeProvider } from '@uhg-abyss/web/ui/theme-provider'; import { createTheme } from '@uhg-abyss/web/tools/theme'; // Brand themes available are 'uhc', 'optum', 'uhg', 'abyss' const theme = createTheme('uhc', { // optional override object }); const App = () => { return ...; }; ``` ### Apply ThemeProvider As shown above, begin by wrapping your application with the `ThemeProvider`. This will enable all Abyss child components to recieve the theme context. For details on available props and configurations, please visit the [ThemeProvider](/web/ui/theme-provider) documentation. ### Create a theme Use the `createTheme` function to generate the base theme configuration and token values for your desired brand theme. As the first argument, this function takes in one of four brand themes, `'uhc | 'optum' | 'uhg' | 'abyss'` and an optional theme override object as a second argument. Once created, provide the theme object into the `theme` prop on `ThemeProvider` as shown above. For more details, see the createTheme documentation. ## Style customization options Now that you've laid the foundation for the theme, you can apply style customizations to Abyss components using the following methods: ### Theme token overrides As mentioned above the `createTheme` function takes in an override object as a second argument. This enables you to adjust theme configurations and apply overrides to the theme tokens. For details on how to implement these token overrides please visit the Theme Overrides section within the `createTheme` documentation. ### Styled tool The `styled` function allows you to create styled components using an object syntax. This provides performance benefits and better developer experience with type checks and autocomplete suggestions. It is also compatible with all theme tokens. ```jsx import { styled } from '@uhg-abyss/web/tools/styled'; const Button = styled('button', { color: 'red', fontSize: '14px', '&:hover': { color: 'black', }, }); ``` For more details, see the [styled](/web/tools/styled) documentation. ### CSS prop You can use the `css` prop to apply styles directly to components. This is useful for quick, minor customizations without creating a separate styled component. It is also compatible with all theme tokens. #### Button example ```jsx live ```
To customize the `Button` component, you can target specific abyss static class names to change the styles. To find the list of available styles, go to the [Integration](/web/ui/button/?tab=integration#integration) tab located on each component's documentation page and find the "Classes" table. Or you can simply inspect the component in the browser to find the abyss class name for the element you'd like to target. ```jsx render ``` ```jsx ``` ```jsx live ``` _Note: Please visit the [accessibility](/web/ui/button?tab=accessibility) tab on each the component's documentation page to read more on designing an accessible component._ ## Other styling options ### Static class names Apart from the customization methods listed above, you can use each components abyss static classes to apply overrides using your style sheets. ```jsx .abyss-box-root { color: lightblue; background-color: verdana; border: 3px solid red; box-shadow: 2px 2px 7px 1px grey; } .abyss-text-input-label { color: white; text-align: center; } ``` ## Related links - [ThemeProvider Documentation](/web/ui/theme-provider) - createTheme Documentation - Theme Token Overrides - [Styling with styled tool](/web/tools/styled) - [Styling with CSS Prop](#css-prop) --- id: intro title: Introduction pagination_prev: web/developers/faq hide_table_of_contents: true --- ### Hello! Welcome to Abyss Tutorials! We will take you through a step-by-step guide on the following: ```jsx render

Create Abyss App
Import Components
Page Routing
Form Building
Theme Customization
Style Components
Create GraphQL API
Connect GraphQL API
State Management

```
We would appreciate any feedback on our tutorial guide. If you are stuck at any time, make sure to contact the Abyss Admiral assigned to your team. If they cannot help, send a help request on our [Contact Page](/web/contact-us/). Before starting, be sure to complete the [Workplace Setup](/web/developers/workplace-setup/) guide. Your first tutorial will be [Create Abyss App](/web/developers/tutorials/create-abyss-app/). Make sure you have this completed before attempting any other tutorial. We hope to spark your creativity for any projects you decide to pursue. Enjoy! --- id: create-abyss-app title: Create Abyss App --- --- **Note:**
We would appreciate any feedback on our tutorial guide. If you are stuck at any time, make sure to contact the Abyss Admiral assigned to your team. If they cannot help, send a help request on our [Contact Page](/web/contact-us/). --- Before starting, be sure to complete the [Workplace Setup](/web/developers/workplace-setup/) guide. ### Step 1: Create an App Now, let's get started. Navigate to your terminal in order to create a new project named **"my-new-app"**. Once there, run the following command: ```bash npx create-abyss-app my-new-app ``` ### Step 2: Navigate to Project Directory Next, navigate into the **my-new-app** project directory by running the command below: ```bash cd my-new-app ``` ### Step 3: Run Abyss Finally, run the following command in order to get localhost running: ```bash npm run web ``` Once you see the screen shown below, you are now up and running with Abyss! ```jsx render const Home = () => { return ( Welcome to Abyss ); }; render(() => { return ; }); ```
Great job, you have successfully created an abyss app! --- id: import-components title: Import Components --- --- **Note:**
We would appreciate any feedback on our tutorial guide. If you are stuck at any time, make sure to contact the Abyss Admiral assigned to your team. If they cannot help, send a help request on our [Contact Page](/web/contact-us/). --- Before starting, be sure to complete the [Create Abyss App](/web/developers/tutorials/create-abyss-app/) tutorial. ### Step 1: Open Home.tsx In Visual Studio Code, open **my-new-app** project. From here, navigate into **products/web/src/routes/Home**, and open the **Home.tsx** file. ```txt └── products └── web ├── src | ├── routes | | └── Home | | ├── index.ts | | └── Home.tsx | ├── browser.tsx | └── document.tsx └── package.json ``` ### Step 2: Import React Anytime you’re using a react component, make sure to import the following dependency at the top: ```jsx import React from 'react'; ``` ### Step 3: Importing Component Depending on the project requirements, the **@uhg-abyss/web/ui**, **@uhg-abyss/web/hooks**, and **@uhg-abyss/web/tools** libraries have different components in order to assemble products quickly. There are multiple ways to customize and integrate components into your project. Let's start with the **Card** component. A Card acts as a container used to display content related to a single subject. You can access the documentation for the [Card](/web/ui/card/) through the Abyss Portal. The import statement for a card should look like this: ```jsx import { Card } from '@uhg-abyss/web/ui/Card'; ``` In **Home.tsx**, within the tsx of **Home** functional component, insert the following code: ```jsx Hello tutorial We did it! ``` ### Step 4: Verifying Your Code Your code in **Home.tsx** should now look like this: ```jsx import React from 'react'; import { Router } from '@uhg-abyss/web/ui/Router'; import { Layout } from '@uhg-abyss/web/ui/Layout'; import { Button } from '@uhg-abyss/web/ui/Button'; import { Card } from '@uhg-abyss/web/ui/Card'; export const Home = () => { return ( Hello tutorial We did it! ); }; ``` ```jsx render const Home = () => { const HeaderContainer = styled('header', { backgroundColor: '$primary1', padding: '$md', textAlign: 'center', }); const ContentContainer = styled('main', { padding: '$md', }); return ( Welcome to Abyss Hello tutorial We did it! ); }; render(() => { return ; }); ```
Great job, you have successfully imported components! --- id: page-routing title: Page Routing --- --- **Note:**
We would appreciate any feedback on our tutorial guide. If you are stuck at any time, make sure to contact the Abyss Admiral assigned to your team. If they cannot help, send a help request on our [Contact Page](/web/contact-us/). --- Before starting, be sure to complete the [Create Abyss App](/web/developers/tutorials/create-abyss-app/) tutorial. ### Step 1: Create A New Page In Visual Studio Code, open **my-new-app** project. From here, navigate into **products/web/src/routes**, and create a new folder, name **"NewPage"**. Within this new folder, we'll be creating two new files, named **"index.ts”** and **"NewPage.tsx"**. ```txt └── products └── web ├── src | ├── routes | | ├── Home | | ├── NewPage | | | ├── index.ts | | | └── NewPage.tsx | ├── browser.tsx | └── document.tsx └── package.json ``` ### Step 2: Add a Component to your New Page In **NewPage.tsx**, insert the following code: ```jsx // Import PageHeader enables us to use headers in our program import { PageHeader } from '@uhg-abyss/web/ui/PageHeader'; // Export const allows us to use NewPage outside of the file (as an import somewhere else) export const NewPage = () => { return ; }; ``` In **index.js**, insert the following export command: ```jsx // Export NewPage allows us to import and use NewPage in Routes export { NewPage } from './NewPage'; ``` Export NewPage allows us to import and use NewPage in Routes ### Step 3: Connecting a Page to the Router Now, in order to run and access our page, we need to connect to the router. In **src/routes/Routes.tsx**, insert the following import command: ```jsx import { NewPage } from './NewPage'; ``` In your Routes function, add the following route within your `` tag: ```jsx } /> ``` ### Note Some routing will require parameters, below is an example of what this would look like: ```jsx } /> ``` This example could be used for social media, here path "handle" would be a placeholder for an element "Profile". Path's URL for 'mySocialMedia' would look like the following: ```jsx mySocialMedia.com / handle; ``` Once the profile element receives a value, the URL would become: ```jsx mySocialMedia.com / myNewProfile; ``` ### Step 4: Accessing New Page Open the page by navigating to [http://localhost:3000/new-page](http://localhost:3000/new-page). Your page should look like this: ```jsx render const NewPage = () => { return ( ); }; render(() => { return ; }); ``` ### Step 5: Create a Link to New Page Using the **Link** or **Button** components, you can navigate between your router's pages. Navigate to the **src/routes/Home/Home.tsx** file, then insert the following import statements: ```tsx import { Link } from '@uhg-abyss/web/ui/Link'; ``` Insert the following **Card.Section** snippets at the bottom of your **Card** component: ```jsx Hello tutorial We did it! Go to New Page ``` In your browser, go back to [http://localhost:3000](http://localhost:3000), and your page should look like this: ```jsx render const Home = () => { const HeaderContainer = styled('header', { backgroundColor: '$primary1', padding: '$md', textAlign: 'center', }); const ContentContainer = styled('main', { padding: '$md', }); return ( Welcome to Abyss Hello tutorial We did it! Go to New Page ); }; render(() => { return ; }); ```
Great job, you have successfully completed page routing! --- id: form-building title: Form Building --- --- **Note:**
We would appreciate any feedback on our tutorial guide. If you are stuck at any time, make sure to contact the Abyss Admiral assigned to your team. If they cannot help, send a help request on our [Contact Page](/web/contact-us/). --- Before starting, be sure to complete the [Create Abyss App](/web/developers/tutorials/create-abyss-app/) tutorial. ### Step 1: Create a Form Page In Visual Studio Code, open **my-new-app** project. From here, navigate into **products/web/src/routes**, and create a new folder, name **"FormPage"**. Within this new folder, we'll be creating two new files, named **"index.ts"** and **"FormPage.tsx"**. Connect your page to the router in **products/web/src/routes/Routes.tsx** by including a new Route shown below: ```jsx } /> ``` You may reference the [Page Routing](/web/developers/tutorials/page-routing/) tutorial for more information on creating pages. ### Step 2: Building A Form Within **FormPage.tsx** we'll be adding the [FormProvider](/web/ui/form-provider) and [TextInput](/web/ui/text-input) components to create a sample form. At the top of your file, copy and paste the following import statements: ```jsx import React from 'react'; import { useForm } from '@uhg-abyss/web/hooks/useForm'; import { FormProvider } from '@uhg-abyss/web/ui/FormProvider'; import { TextInput } from '@uhg-abyss/web/ui/TextInput'; ``` A form can consist of many types of input components. In this form, we are using **TextInput** to populate the user's first name, middle name, and last name. Make sure all inputs are children of the **FormProvider** component. Also be sure to provide default values for each field to the `defaultValues` prop within `useForm`. This ensures the form will properly reset to these default values whenever calling the `reset` method. ```jsx live const FormPage = () => { const emptyDefaultValues = { firstName: '', lastName: '', middleName: '', }; const form = useForm({ defaultValues: emptyDefaultValues, }); return ( ); }; render(() => { return ; }); ``` We can also include a **SelectInput** component as another alternative to collecting user input. Import your **SelectInput** component, and then add the following code after the last **TextInput** component: ```jsx ``` ```jsx live const FormPage = () => { const emptyDefaultValues = { firstName: '', lastName: '', middleName: '', favoriteFruit: '', }; const form = useForm({ defaultValues: emptyDefaultValues, }); return ( ); }; render(() => { return ; }); ``` Lastly, we will create buttons in order to submit and clear the form inputs. The **Layout** component will be utilized in order to format the page. Import the **Button** and **Layout** components, and then after the last **SelectInput** that you added above, within the body of **FormProvider**, insert the following code: ```jsx ``` Let's add handlers for our submit and clear functions. Below the **useForm()** hook, add the two functions below for **handleSubmit** and **handleClear**. ```jsx const emptyDefaultValues = { firstName: '', lastName: '', middleName: '', favoriteFruit: '', }; const form = useForm({ defaultValues: emptyDefaultValues, }); const handleSubmit = (data) => { console.log('Form Data', data); alert('Submitted!'); }; const handleClear = () => { form.reset(); }; ``` Finally, attach the **handleSubmit** function by adding an **onSubmit** prop to your **FormProvider**. ```jsx ``` ```jsx live const FormPage = () => { const emptyDefaultValues = { firstName: '', lastName: '', middleName: '', favoriteFruit: '', }; const form = useForm({ defaultValues: emptyDefaultValues, }); const handleSubmit = (data) => { console.log('Form Data', data); alert('Submitted!'); }; const handleClear = () => { form.reset(); }; return ( ); }; render(() => { return ; }); ``` ### Step 3: Testing your Form At the end of creating a form & submitting the data, your code in **FormPage.tsx** should look like this: ```jsx import React from 'react'; import { useForm } from '@uhg-abyss/web/hooks/useForm'; import { FormProvider } from '@uhg-abyss/web/ui/FormProvider'; import { TextInput } from '@uhg-abyss/web/ui/TextInput'; import { SelectInput } from '@uhg-abyss/web/ui/SelectInput'; import { Button } from '@uhg-abyss/web/ui/Button'; import { Layout } from '@uhg-abyss/web/ui/Layout'; export const FormPage = () => { const emptyDefaultValues = { firstName: '', lastName: '', middleName: '', favoriteFruit: '', }; const form = useForm({ defaultValues: emptyDefaultValues, }); const handleSubmit = (data) => { console.log('Form Data', data); alert('Submitted!'); }; const handleClear = () => { form.reset(); }; return ( ); }; ``` Great job, you have successfully built a form! --- id: state-management title: State Management --- --- **Note:**
We would appreciate any feedback on our tutorial guide. If you are stuck at any time, make sure to contact the Abyss Admiral assigned to your team. If they cannot help, send a help request on our [Contact Page](/web/contact-us/). --- Before starting, be sure to complete the [Create Abyss App](/web/developers/tutorials/create-abyss-app/) tutorial. ### Step 1: Creating a Store Navigate to **products/web/src/hooks**. Create a folder named **"useStore"** in the **hooks** folder. In your newly created **useStore** folder, create a file called **"useStore.ts"**. Within **useStore.ts**, first begin by importing the [createStore](/web/tools/create-store) tool. This tool allows you to leverage the zustand library and provides access to its full list of features. Add the following code below to **useStore.ts**. Within this block of code, there are the properties `formOne` and `formTwo`, which will hold the current state of the field values for the two forms, along with `setForms`, which will be used in combination with the createStore `set` function to update and immutably merge state. For a more in-depth overview of the **createStore** tool please visit the following [page](/web/tools/create-store). Now let's move on to updating **FormPage.tsx** to access our newly created store. ```jsx import { createStore } from '@uhg-abyss/web/tools/createStore'; export const useStore = createStore((set) => { return { formOne: null, formTwo: null, setForms: (formValues) => { return set(() => { return { ...formValues }; }); }, }; }); ``` ### Step 2: Add Store to Form Page One As part of this tutorial, we're going to utilize a set of forms to demonstrate the use of state management within your application. To begin, we will be leveraging the form we created earlier during the [Form Building](/web/developers/tutorials/form-building) section of the tutorials. If you have yet to complete this step, please navigate to this [page](/web/developers/tutorials/form-building) and finish before continuing. Navigate to the **FormPage** folder and open **FormPage.tsx**. Next, import the `useStore` hook we just created, along with the React `useEffect` hook. ```jsx import React, { useEffect } from 'react'; import { useStore } from '../../hooks/useStore/useStore'; ``` Add the code below inside **FormPage** to connect to our store and retrieve the current form values and `setForms` method: ```jsx const { formOne: currentStoreValues, setForms } = useStore(); ``` Modify `useForm` to set the default values on load to either the current store values if present, otherwise supply the empty defaults: ```jsx const emptyDefaultValues = { firstName: '', lastName: '', middleName: '', favoriteFruit: '', }; const form = useForm({ defaultValues: currentStoreValues || emptyDefaultValues, }); ``` Add a `useEffect` with a return statement that will write the current form values to our store whenever leaving the page: ```jsx useEffect(() => { return () => { const currentFormValues = form.getValues(); setForms({ formOne: currentFormValues }); }; }, []); ``` Lastly, add a button that will navigate to **FormPageTwo** which we will be creating in the next step of this tutorial. Your updated **FormPage.tsx** should look like this: ```jsx import React, { useEffect } from 'react'; import { useForm } from '@uhg-abyss/web/hooks/useForm'; import { FormProvider } from '@uhg-abyss/web/ui/FormProvider'; import { TextInput } from '@uhg-abyss/web/ui/TextInput'; import { SelectInput } from '@uhg-abyss/web/ui/SelectInput'; import { Button } from '@uhg-abyss/web/ui/Button'; import { Layout } from '@uhg-abyss/web/ui/Layout'; import { styled } from '@uhg-abyss/web/tools/styled'; import { useStore } from '../../hooks/useStore/useStore'; const ButtonsContainer = styled('div', { display: 'flex', }); export const FormPage = () => { const emptyDefaultValues = { firstName: '', lastName: '', middleName: '', favoriteFruit: '', }; const { formOne: currentStoreValues, setForms } = useStore(); const form = useForm({ defaultValues: currentStoreValues || emptyDefaultValues, }); useEffect(() => { return () => { const currentFormValues = form.getValues(); setForms({ formOne: currentFormValues }); }; }, []); const handleSubmit = (data) => { console.log('Form Data', data); alert('Submitted!'); }; const handleClear = () => { form.reset(emptyDefaultValues); }; return ( ); }; ``` ### Step 3: Creating Form Page Two Now that we have updated our first form page, we'll move on to creating the second. In Visual Studio Code, open the **my-new-app** project. From here, navigate into **products/web/src/routes** and create a new folder named **"FormPageTwo"**. Within this new folder, we'll be creating two new files named **"index.ts"** and **"FormPageTwo.tsx"**. Remember to connect your page to the router in **products/web/src/routes/Routes.tsx** by including a new Route shown below: ```jsx } /> ``` You may refer to the [Page Routing](/web/developers/tutorials/page-routing/) tutorial for more information on creating pages. Navigate to the **FormPageTwo** folder and insert the following code in the **index.ts** file: ```jsx export { FormPageTwo } from './FormPageTwo'; ``` Now within **FormPageTwo.tsx**, add the following imports: ```jsx import React, { useEffect } from 'react'; import { useStore } from '../../hooks/useStore/useStore'; import { useForm } from '@uhg-abyss/web/hooks/useForm'; import { FormProvider } from '@uhg-abyss/web/ui/FormProvider'; import { DateInput } from '@uhg-abyss/web/ui/DateInput'; import { TimeInput } from '@uhg-abyss/web/ui/TimeInput'; import { Button } from '@uhg-abyss/web/ui/Button'; import { Layout } from '@uhg-abyss/web/ui/Layout'; ``` Next, similar to **FormPage**, add the following code below to connect our form to our store: ```jsx export const FormPageTwo = () => { const emptyDefaultValues = { date: '', time: '', }; const { formTwo: currentStoreValues, setForms } = useStore(); // retrieve the current state from our store const form = useForm({ defaultValues: currentStoreValues || emptyDefaultValues, // on page load supply our form default values with the currentStoreValues if present, otherwise supply the empty defaults }); // ensure that whenever leaving the page our store is always updated with the current form values useEffect(() => { return () => { const updatedFormValues = form.getValues(); // retrieve current form field values setForms({ formTwo: updatedFormValues }); // call setForms and pass in the formTwo current values }; }, []); const handleSubmit = (data) => { console.log('Form Data', data); alert('Submitted!'); }; const handleClear = () => { form.reset(emptyDefaultValues); }; }; ``` Lastly, add the components to construct our form UI: ```jsx return ( ); ``` Your **FormPageTwo.tsx** should look like this: ```jsx import React, { useEffect } from 'react'; import { useStore } from '../../hooks/useStore/useStore'; import { useForm } from '@uhg-abyss/web/hooks/useForm'; import { FormProvider } from '@uhg-abyss/web/ui/FormProvider'; import { DateInput } from '@uhg-abyss/web/ui/DateInput'; import { TimeInput } from '@uhg-abyss/web/ui/TimeInput'; import { Button } from '@uhg-abyss/web/ui/Button'; import { Layout } from '@uhg-abyss/web/ui/Layout'; import { styled } from '@uhg-abyss/web/tools/styled'; const ButtonsContainer = styled('div', { display: 'flex', }); export const FormPageTwo = () => { const emptyDefaultValues = { date: '', time: '', }; const { formTwo: currentStoreValues, setForms } = useStore(); const form = useForm({ defaultValues: currentStoreValues || emptyDefaultValues, }); useEffect(() => { return () => { const currentFormValues = form.getValues(); setForms({ formTwo: currentFormValues }); }; }, []); const handleSubmit = (data) => { console.log('Form Data', data); alert('Submitted!'); }; const handleClear = () => { form.reset(emptyDefaultValues); }; return ( ); }; ``` ### Step 4: Testing your Store At the end of this tutorial, your output should look similar to what's below. As you interact with the forms and navigate between the pages, you should see that the values persist and always represent the latest state. ```jsx render () => { const [showPageOne, setShowPageOne] = useState(true); const ButtonsContainer = styled('div', { display: 'flex', }); const PageOneForm = React.memo(() => { const defaultValues = { firstName: '', lastName: '', middleName: '', favoriteFruit: '', }; const { formOne: currentStoreValues, setForms } = utils.useStore(); const form = useForm({ defaultValues: currentStoreValues || defaultValues, }); useEffect(() => { return () => { const currentFormValues = form.getValues(); setForms({ formOne: currentFormValues }); }; }, []); const handleClear = () => { form.reset(defaultValues); }; const handleSubmit = (data) => { console.log('Form Data', data); alert('Submitted!'); }; return ( Page One Form ); }); const PageTwoForm = React.memo(() => { const defaultValues = { date: '', time: '', }; const { formTwo: currentStoreValues, setForms } = utils.useStore(); const form = useForm({ defaultValues: currentStoreValues || defaultValues, }); useEffect(() => { return () => { const currentFormValues = form.getValues(); setForms({ formTwo: currentFormValues }); }; }, []); const handleClear = () => { form.reset(defaultValues); }; const handleSubmit = (data) => { console.log('Form Data', data); alert('Submitted!'); }; return ( Page Two Form ); }); return showPageOne ? : ; }; ```
Great job, you have successfully created a store! --- id: custom-themes title: Custom Themes --- --- **Note:**
We would appreciate any feedback on our tutorial guide. If you are stuck at any time, make sure to contact the Abyss Admiral assigned to your team. If they cannot help, send a help request on our [Contact Page](/web/contact-us/). --- Before starting, be sure to complete the [Create Abyss App](/web/developers/tutorials/create-abyss-app/) tutorial. ### Step 1: Create a Theme Page In Visual Studio Code, open **my-new-app** project. From here, navigate into **products/web/src/routes**, and create a new folder, name **"ThemePage"**. Within this new folder, we'll be creating two new files, named **"index.ts"** and **"ThemePage.tsx"**. Remember to connect your page to the router in **products/web/src/routes/Routes.tsx** by including a new Route shown below: ```jsx } /> ``` You may reference the [Page Routing](/web/developers/tutorials/page-routing/) tutorial for more information on creating pages. ### Step 2: Choosing A Theme Abyss currently has pre-defined themes for Optum, UHC, and UHG brands. In **products/web/src/browser.tsx**, you will see `const theme = createTheme('uhg');`. Within this **createTheme** function, you can choose between these different brands demonstrated below: [Optum Theme](/web/brand/optum/brandmark/) ```jsx const theme = createTheme('optum'); ``` [UHC Theme](/web/brand/uhc/brandmark/) ```jsx const theme = createTheme('uhc'); ``` [UHG Theme](/web/brand/uhg/brandmark/) ```jsx const theme = createTheme('uhg'); ``` ### Step 3: Customizing your Theme If you need to customize these default themes to meet your product's branding, you can include a configuration to override variables within the theme that are used to style Abyss components. There are many ways to customize and style your application. For now, we will be focusing on color and font customization. If you are curious to learn more about other options, check out [ThemeProvider](/web/ui/theme-provider/). The code below shows how to customize a theme to your preferences. In **browser.tsx**, add the following configurations to your theme: ```jsx const theme = createTheme('uhg', { theme: { colors: { primary1: 'hotpink', interactive1: 'purple', }, fonts: { primary: 'Monospace', heading: 'Monaco', }, }, }); ``` ### Step 4: Viewing Theme To view some of your theme updates, import some Abyss components into your **ThemePage.tsx** and see how they look! ```jsx import React from 'react'; import { Heading } from '@uhg-abyss/web/ui/Heading'; import { Button } from '@uhg-abyss/web/ui/Button'; export const ThemePage = () => { return (

Themed Heading

); }; ``` In your browser, your ThemePage should look like this: ```jsx render const ThemePage = () => { const theme = createTheme('uhg', { theme: { colors: { primary1: 'hotpink', interactive1: 'purple', }, fonts: { primary: 'Monospace', heading: 'Monaco', }, }, }); return ( Themed Heading ); }; render(() => { return ; }); ```
Great job, you have successfully customized a theme! --- id: styled-components title: Styled Components --- --- **Note:**
We would appreciate any feedback on our tutorial guide. If you are stuck at any time, make sure to contact the Abyss Admiral assigned to your team. If they cannot help, send a help request on our [Contact Page](/web/contact-us/). --- Before starting, be sure to complete the [Create Abyss App](/web/developers/tutorials/create-abyss-app/) tutorial. ### Step 1: Create a Styled Page In Visual Studio Code, open **my-new-app** project. From here, navigate into **products/web/src/routes**, and create a new folder, name **"StyledPage"**. Within this new folder, we'll be creating two new files, named **"index.ts"** and **"StyledPage.tsx"**. Remember to connect your page to the router in **products/web/src/routes/Routes.tsx** by including a new Route shown below: ```jsx } /> ``` You may reference the [Page Routing](/web/developers/tutorials/page-routing/) tutorial for more information on creating pages. ### Step 2: Creating Styled Components You can use the **styled** tool to style html elements. It uses JSS to create CSS classes within JavaScript. Styling can consist of changing a component's font, color, size, padding, and spacing, etc. If you are curious to learn more about other options, check out [styled](/web/tools/styled/). In your **StyledPage.tsx** file, add the following import statements: ```jsx import React from 'react'; import { styled } from '@uhg-abyss/web/tools/styled'; import { Text } from '@uhg-abyss/web/ui/Text'; import { Layout } from '@uhg-abyss/web/ui/Layout'; import { IconBrand } from '@uhg-abyss/web/ui/IconBrand'; ``` We will create an information box to demonstrate how to use **styled**. After your import statements, insert the following code: ```jsx const StyledContainer = styled('div', { padding: '$lg', }); const StyledBox = styled('div', { display: 'inline-block', border: '1px solid $gray4', borderRadius: 8, padding: '0 $md', backgroundColor: '$info2', }); const StyledIcon = styled(IconBrand, { border: '1px solid $gray4', borderRadius: '50%', }); ``` ### Step 3: Rendering Styled Components In your **StyledPage.tsx** file, add following code below to your **StyledPage** component: ```jsx export const StyledPage = () => { return ( Average cost in your area: $980 ); }; ``` This component uses the **StyledBox** and **StyledContainer** components we created previously. There are other features on the [styled](/web/tools/styled/) page to customize and edit your components to best fit your product's custom designs. ### Step 4: Viewing Styled Components At the end of this tutorial, your code in your **StyledPage.tsx** file should look like this: ```jsx import React from 'react'; import { styled } from '@uhg-abyss/web/tools/styled'; import { Text } from '@uhg-abyss/web/ui/Text'; import { Layout } from '@uhg-abyss/web/ui/Layout'; import { IconBrand } from '@uhg-abyss/web/ui/IconBrand'; const StyledContainer = styled('div', { padding: '$lg', }); const StyledBox = styled('div', { display: 'inline-block', border: '1px solid $gray4', borderRadius: 8, padding: '$xs $md', backgroundColor: '$info2', }); const StyledIcon = styled(IconBrand, { border: '1px solid $gray4', borderRadius: '50%', }); export const StyledPage = () => { return ( Average cost in your area: $980 ); }; ``` In your browser, your StyledPage should look like this: ```jsx live const StyledContainer = styled('div', { padding: '$lg', }); const StyledBox = styled('div', { display: 'inline-block', border: '1px solid $gray4', borderRadius: 8, padding: '$xs $md', backgroundColor: '$info2', }); const StyledIcon = styled(IconBrand, { border: '1px solid $gray4', borderRadius: '50%', }); const StyledPage = () => { return ( Average cost in your area: $980 ); }; render(() => { return ; }); ```
Great job, you have successfully styled components! --- id: graphql-endpoints title: GraphQL Endpoints --- --- **Note:**
We would appreciate any feedback on our tutorial guide. If you are stuck at any time, make sure to contact the Abyss Admiral assigned to your team. If they cannot help, send a help request on our [Contact Page](/web/contact-us/). --- Before starting, be sure to complete the [Create Abyss App](/web/developers/tutorials/create-abyss-app/) tutorial. ### Step 1: Running Your API Server Make sure you have completed all previous tutorial pages and ran them successfully. We will now be shifting our focus from the front-end of the application to the back-end API. In your Terminal, navigate into the **my-new-app** directory. Once there, run the following command: ```bash npm run api ``` Once you see the screen shown below, your API server is now up and running! drawing

### Step 2: Adding Mock Data & Service Navigate to **products/api/src/services**. Within the **services** folder, create a folder named **"person"**. Within this **person** folder, create an **"index.ts"** file. ```txt └── products └── api ├── src | ├── routes | | └── graphql | ├── services | | └── person | | └── index.ts | └── server.ts └── package.json ``` Add the following code in **index.ts**: ```js // this is a mock database with name, email, company and location properties for each person const personDB = { dolphin: { name: 'Danny Dolphin', email: 'danny@optum.com', company: 'Optum', location: 'Atlantic Ocean', }, whale: { name: 'Willy Whale', email: 'willy@uhg.com', company: 'UHG', location: 'Pacific Ocean', }, penguin: { name: 'Penny Penguin', email: 'penny@uhc.com', company: 'UHC', location: 'Arctic Ocean', }, }; export const personServices = { getPerson: async (args) => { const data = personDB[args.msid]; return data; }, }; ``` ### Step 3: Adding A GraphQL Schema A GraphQL schema allows you to receive specific data from the database based on the request call. The schema allows the data to be used and displayed in the GraphQL sandbox. Navigate to **products/api/src/routes/graphql/schema**. Within the **schema** folder, create a file named **"Person.graphql"**. Add the following code in your **Person.graphql** file: ```jsx # ID is a type, similar to a String. The exclamation(!) makes it a required field extend type Query { person(msid: ID!): Person } # type Person contains the information we want from the database type Person { name: String email: String company: String location: String } ``` ### Step 4: Adding A GraphQL Resolver We will now be adding a resolver, which acts as a GraphQL query handler. Navigate to **products/api/src/routes/graphql/resolvers.ts** Import the following statement: ```js import { personServices } from '../../services/person'; ``` Insert the following code within the export query statement: ```js person: (_, args) => { return personServices.getPerson(args); }, ``` This is how your code should look like in your **resolvers.ts** file: ```js import { githubServices } from '../../services/github'; import { personServices } from '../../services/person'; export const resolvers = { Query: { user: (_, args) => { return githubServices.getUser(args); }, person: (_, args) => { return personServices.getPerson(args); }, }, }; ``` ### Step 5: Accessing GraphQL API Make sure you are running `npm run api` in your terminal. To check if you successfully created a GraphQL API, click the following link in your browser: [GraphQL Sandbox Explorer](http://localhost:4000/graphql) Once you launch your GraphQL webpage, follow the instructions in the following images: drawing

{' '}

{' '} ### Step 6: Swapping Mock Data for Live DataSource Navigate to **products/api/src/services/person/index.ts**. Replace the current code in **index.ts** with the following code: ```js import { dataSource } from '@uhg-abyss/api/tools/dataSource/rest'; // create a connection to the GitHub API const personAPI = dataSource({ url: 'https://github.optum.com/api/v3', }); export const personServices = { getPerson: async (args) => { const { data } = await personAPI({ method: 'GET', path: `/users/${args.msid}`, }); return data; }, }; ``` You can try inserting your msid in the variable section and click the query button to see a corresponding query response. If yours doesn't work use someone elses MSID - example: "jhollow6" Great job, you have successfully created a GraphQL API! --- id: graphql-requests title: GraphQL Requests pagination_next: null --- --- **Note:**
We would appreciate any feedback on our tutorial guide. If you are stuck at any time, make sure to contact the Abyss Admiral assigned to your team. If they cannot help, send a help request on our [Contact Page](/web/contact-us/). --- Before starting, be sure to complete the [Create Abyss App](/web/developers/tutorials/create-abyss-app/) tutorial. ### Step 1: Running Your Full-Stack Application Make sure you have completed all previous tutorial pages successfully. [GraphQL Endpoints](/web/developers/tutorials/graphql-endpoints/) is a prerequisite to this tutorial and must be completed beforehand. In your Terminal, navigate into the **my-new-app** folder. Once there, run the following command: ```bash npm run dev ``` This command will start parallel servers for both the Web & API products on your localhost. ### Step 2: Create a Query Page In Visual Studio Code, open **my-new-app** project. From here, navigate into **products/web/src/routes**, and create a new folder, name **"QueryPage"**. Within this new folder, we'll be creating two new files, named **"index.js"** and **"QueryPage.jsx"**. Remember to connect your page to the router in **products/web/src/routes/Routes.jsx** by including a new Route shown below: ```jsx } /> ``` You may reference the [Page Routing](/web/developers/tutorials/page-routing/) tutorial for more information on creating pages. ### Step 2: Creating A Client Query A query fetches requested data from the API server. In order to receive information on certain data we want from our GraphQL API, we must create a query from our web client. In this step, we are using the previous built query from our Apollo sandbox in order to search and receive the data being requested. By using the **msid** as an ID variable for our query, we should be able to retrieve a person's name, email, company, and location. Navigate to **products/web/src**. Create a folder named **"hooks"** in the **src** folder. In your newly created **hooks** folder, create a folder called **"usePersonSearch"**. In the **usePersonSearch** folder, create the following files: **"GetPerson.gql"**, **"index.js"** and **"usePersonSearch.js"**. Insert the following code in the **GetPerson.gql** file: ```jsx query Person($personId: ID!) { person(msid: $personId) { name email company location } } ``` Insert the following code in the **index.js** file: ```js export { usePersonSearch } from './usePersonSearch'; ``` Insert the following code in the **usePersonSearch.js** file: ```js import { useQuery } from '@uhg-abyss/web/hooks/useQuery'; import GetPerson from './GetPerson.gql'; export const usePersonSearch = (options) => { return useQuery(GetPerson, { ...options, url: '/api/graphql', accessor: 'person', initialState: { name: '', email: '', company: '', location: '', }, }); }; ``` ### Step 4: Querying From Your App Now, we will be calling the query from within our application. We will be integrating a submit button and search box to run our query search. Navigate to **products/web/src/routes/QueryPage/QueryPage.jsx**. Replace the current code in **QueryPage.jsx** with the following code: ```jsx import React, { useState } from 'react'; import { Button } from '@uhg-abyss/web/ui/Button'; import { TextInput } from '@uhg-abyss/web/ui/TextInput'; import { usePersonSearch } from '@src/hooks/usePersonSearch'; export const QueryPage = () => { const [searchValue, setSearchValue] = useState(); const [personSearchResult, getPersonSearch] = usePersonSearch(); const { person } = personSearchResult.data; const handleSearch = () => { getPersonSearch({ variables: { personId: searchValue, }, }); }; const handleChange = (e) => { setSearchValue(e.target.value); }; return (

Name: {person?.name}
Email: {person?.email}
Company: {person?.company}
Location: {person?.location}

); }; ``` ### Step 5: Running Query On Webpage Your page should look like this. Insert your **msid** in the text input box, then click the **Search** button to run the query and get the relevant data. drawing

{' '}
Great job, you have successfully connected to a GraphQL API! --- **Congratulations! You have completed all the tutorials and are an Abyss expert. You are ready to venture off on your own Abyss path and start your journey!** --- --- id: versioning-guide title: Versioning Guide --- ## Overview Stability ensures that reusable components and libraries, tutorials, tools, and learned practices don't become obsolete unexpectedly. Stability is essential for the ecosystem around Abyss to thrive. This document contains the practices that are followed to provide you with a leading-edge UI library, balanced with stability, ensuring that future changes are always introduced in a predictable way. ## Semantic versioning Abyss follows Semantic Versioning 2.0.0. Abyss version numbers have three parts: major.minor.patch. The version number is incremented based on the level of change included in the release. - **Major releases** contain significant new features, some but minimal developer assistance is expected during the update. When updating to a new major release, you may need to run update scripts, refactor code, run additional tests, and learn new APIs. - **Minor releases** contain important new features. Minor releases should be fully backward-compatible; no developer assistance is expected during update, but you can optionally modify your apps and libraries to begin using new APIs, features, and capabilities that were added in the release. - **Patch releases** are low risk, contain bug fixes and small new features. No developer assistance is expected during update. ## Release frequency A regular schedule of releases helps you plan and coordinate your updates with the continuing evolution of Abyss. In general, you can expect the following release cycle: - A **major** release typically every year for major changes. - A **minor** releases every two weeks after each sprint. - A **patch** release at any time for urgent bugfixes. ## Deprecation practices Sometimes **"breaking changes"**, such as the removal of support for select APIs and features, are necessary. To make these transitions as easy as possible: - The number of breaking changes is minimized, and migration tools provided when possible. - The deprecation policy described below is followed, so that you have time to update your apps to the latest APIs and best practices. ## Deprecation policy - Deprecated features are announced in the changelog, and when possible, with warnings at runtime. - When a deprecation is announced, recommended update path is provided. - Existing use of a stable API during the deprecation period is supported, so your code will keep working during that period. - Peer dependency updates (React) that require changes to your apps are only made in a major release. --- id: workplace-setup title: Workplace Setup --- ## Overview Developing modern JavaScript applications requires efficient, powerful, and extensible tooling. Consistency across developer machines is a priority when collaborating across highly distributed teams. The following is a guide for installing the preferred environment for JS development. ![workspace setup](/img/graphics/workspace.svg) ## Secure groups Visit secure.uhc.com to request permissions groups: - **github_users**: To access github.com - **Mac_Admin**: To install software for macOS users only ## VSCode Editor To write code for UI projects, it is **highly recommended** that you download and install Visual Studio Code. ![Visual Studio Code](https://code.visualstudio.com/assets/home/home-screenshot-mac-lg-2x.png) ## VSCode extensions Recommended extensions will be suggested to you when you visit the VSCode Marketplace. - ESLint : code syntax validator ESLint is a JavaScript linting tool which is used for automatically detecting incorrect patterns found in ECMAScript/JavaScript code. It is used with the purpose of improving code quality, making code more consistent, and avoiding bugs. Rules can be configured to look for all kinds of discrepancies due to discouraged code patterns or formatting. Running a Linting tool over the source code helps to improve the quality and readability of the code. - Prettier : code formatter Prettier is very popular because it improves code readability and makes the coding style consistent for teams. Developers are more likely to adopt a standard rather than writing their own code style from scratch, so tools like Prettier will make your code look good without you ever having to dabble in the formatting. ## Chrome browser To install Google Chrome, use the "Self Service" application on your desktop. ![Google Chrome](/img/graphics/google_chrome.png) ## Chrome browser extensions In Chrome, you may install the following recommended extensions: - React Developer Tools - Google Lighthouse - axe DevTools ## System essentials To run all JS-based applications, it is **highly recommended** to have these tools installed: - Xcode Command Line Tools (Mac Only) `xcode-select` contains necessary utilities for software development on macOS. ```bash xcode-select --install ```
**_After install, exit and restart Terminal (CMD + Q)_** ``` xcode-select --version ```
--- - oh-my-zsh >= 5.3.0 (optional) `zsh` is an optional upgrade to the native shell which provides a delightful terminal experience. ```bash sh -c "$(curl -fsSL https://raw.githubusercontent.com/robbyrussell/oh-my-zsh/master/tools/install.sh)" ```
**_After install, exit and restart Terminal (CMD + Q)_** ```bash omz version ```
--- - node >= 16.0.0 `nvm` is a great tool for installing and upgrading versions of Node on your system. ```bash curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.1/install.sh | bash ```
**_After install, exit and restart Terminal (CMD + Q)_** ```bash nvm --version nvm install 16 && nvm use 16 && nvm alias default 16 ```
**_After install, exit and restart Terminal (CMD + Q)_** ``` npm --version npm config set registry https://repo1.uhc.com/artifactory/api/npm/npm-virtual ```
--- export const gitLink = 'https://git-scm.com/book/en/v2/Getting-Started-Installing-Git'; - git >= 2.0.0 `git` is a universal version control system for working collaboratively and efficiently. ```bash git config --global user.id "YOUR_MS_ID" git config --global user.email "YOUR_EMAIL@optum.com" ``` --- id: use-collapse category: UI & DOM title: useCollapse description: Show or hide associated section of content. pagination_prev: web/hooks/use-router pagination_next: web/hooks/use-fuse --- ```jsx import { useCollapse } from '@uhg-abyss/web/hooks/useCollapse'; ``` ## Usage Use the `defaultIsOpen` prop to set the initial state for collapse container. The `duration` prop is defaulted to `300ms`, we can pass custom values to vary the transition time. ```jsx live () => { const { collapseProps, buttonProps, isOpen } = useCollapse(); return ( Collapse Example: {isOpen ? 'Collapse' : 'Expand'}

Aliquam non felis convallis, tempus eros vel, sagittis augue.
Praesent hendrerit ipsum viverra, facilisis risus et, sollicitudin massa.
Morbi tincidunt metus vitae quam semper hendrerit.
Fusce accumsan mi ut risus molestie, pretium fringilla risus consectetur.
Nullam vel mi gravida, eleifend est vitae, semper mauris.

); }; ``` ## Maximum duration The `duration` prop allows Maximum value of `1500ms` for the transition timing to show and hide content. If developer enters the duration greater than max duration value(1500ms) we will assign duration to `1500ms`. default value is `300ms`. For users who have `prefers-reduced-motion` set to `reduced` for accessibility reasons, the duration is overridden to `0ms` to prevent the animation transition. ```jsx live () => { const { collapseProps, buttonProps, isOpen } = useCollapse({ duration: 1500, }); return ( Collapse Example: {isOpen ? 'Collapse' : 'Expand'}

Showing Content Based on Duration

Aliquam non felis convallis, tempus eros vel, sagittis augue.
Praesent hendrerit ipsum viverra, facilisis risus et, sollicitudin massa.
Morbi tincidunt metus vitae quam semper hendrerit.
Fusce accumsan mi ut risus molestie, pretium fringilla risus consectetur.
Nullam vel mi gravida, eleifend est vitae, semper mauris.

); }; ``` ## Collapsing multiple To control the expand/collapse functionality of multiple collapsible containers utilize the `CollapseProvider`. Visit the [CollapseProvider](/web/ui/collapse-provider) page for more details and examples on implementation. ```jsx live () => { const CollapseList = ({ defaultIsOpen }) => { const { collapseProps, buttonProps, isOpen } = useCollapse({ defaultIsOpen, }); return ( Collapse Example: {isOpen ? 'Collapse' : 'Expand'}

Aliquam non felis convallis, tempus eros vel, sagittis augue.
Praesent hendrerit ipsum viverra, facilisis risus et, sollicitudin massa.
Morbi tincidunt metus vitae quam semper hendrerit.
Fusce accumsan mi ut risus molestie, pretium fringilla risus consectetur.
Nullam vel mi gravida, eleifend est vitae, semper mauris.

); }; return ( ); }; ``` ## Properties ```typescript useCollapse( defaultIsOpen?: boolean, ref?: object, duration?: number, ): object; ``` --- id: use-countdown category: Utilities title: useCountdown description: The useCountdown is a custom hook for countdown capility. pagination_prev: web/hooks/use-scroll-trigger pagination_next: web/hooks/use-token --- ```jsx import { useCountdown } from '@uhg-abyss/web/hooks/useCountdown'; ``` ```jsx live () => { const { formattedTime } = useCountdown({ time: 10 * 60 * 1000 }); return {formattedTime}; }; ``` ## Callback function You can specify a callback function that will be executed every time the countdown reaches zero. ```jsx live () => { const [isComplete, setComplete] = useState(false); const onCompleted = () => setComplete(true); const { formattedTime } = useCountdown({ time: 15 * 1000, onCompleted }); if (isComplete) { return ( Time's Up! ); } return {formattedTime}; }; ``` ## Reset countdown time Use the `resetCountdown` function returned by the hook to reset the countdown back to its starting value. ```jsx live () => { const [isComplete, setComplete] = useState(false); const onCompleted = () => setComplete(true); const { formattedTime, resetCountdown } = useCountdown({ time: 5 * 1000, onCompleted, }); if (isComplete) { return ( Time's Up! ); } return ( {formattedTime} ); }; ``` ## Set countdown time Use the `setCountdownTme` function returned by the hook to set the countdown to a new time. ```jsx live () => { const [isComplete, setComplete] = useState(true); const onCompleted = () => setComplete(true); const { formattedTime, setCountdownTime } = useCountdown({ time: 0, onCompleted, }); if (isComplete) { return ( Time's Up! ); } return {formattedTime}; }; ``` ## Output ```jsx live () => { const countdown = useCountdown({ time: 31556952000 }); return

{JSON.stringify(countdown, null, 2)}

; }; ``` --- id: use-form-v2 category: State Management title: useFormV2 description: useForm is a hook for defining, validating and submitting forms. subDirectory: useForm/v2 sourceIsTS: true --- ```jsx import { useFormV2 } from '@uhg-abyss/web/hooks/useForm'; ``` ```jsx render ``` ## Usage ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); const onSubmit = (data) => { // Do something on submit alert(`FormData: ${JSON.stringify(data)}`); }; return ( Submit ); }; ``` ## Default values The defaultValues prop populates the entire form with default values. It supports both synchronous and asynchronous assignments of default values. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); // Default Values Passed into useForm const form = useFormV2({ defaultValues: { firstName: 'John', lastName: 'Doe', }, }); const onSubmit = (data) => { alert(`FormData: ${JSON.stringify(data)}`); }; return ( Submit ); }; ``` ## Values The values props will react to changes and update the form values, which is useful when your form needs to be updated by external state or server data. ```jsx // set default value sync function App({ values }) { useFormV2({ values, // will get updated when values props updates }); } function App() { const values = useFetch('/api'); useFormV2({ defaultValues: { firstName: '', lastName: '', }, values, // will get updated once values returns }); } ``` ## Form state This object contains information about the form state. If you want to subscribe to formState via useEffect, make sure that you place the entire formState in the optional array. ```jsx const form = useFormV2(); const { errors, // An object with field errors isDirty, // Set to true after the user modifies any of the inputs. isValid, // Set to true if the form doesn't have any errors. isValidating, // Set to true during validation. isSubmitting, // true if the form is currently being submitted; false if otherwise. isSubmitted, // Set to true after the form is submitted. isSubmitSuccessful, // Indicate the form was successfully submitted without any Promise rejection or Error being thrown within the handleSubmit callback. submitCount, // Number of times the form was submitted. touchedFields, // An object containing all the inputs the user has interacted with. dirtyFields, // An object with the user-modified fields. } = form.formState; ``` ## Watch This will watch specified inputs and return their values. It is useful for determining what to render. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); const onSubmit = (data) => { alert(`FormData: ${JSON.stringify(data)}`); }; // Watch one field const WatchField = form.watch('firstName'); // Target specific fields by their names const WatchFields = form.watch(['firstName', 'lastName']); // Watch everything by passing no arguments const WatchAllFields = form.watch(); return ( Submit

Watch one field: {JSON.stringify(WatchField)}

Watch multiple fields: {JSON.stringify(WatchFields)}

Watch all fields: {JSON.stringify(WatchAllFields)}

); }; ``` ## Handle submit This function will receive the form data if form validation is successful. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2({ defaultValues: { firstName: 'John', lastName: 'Doe', }, }); const onSubmit = (data, e) => alert('onSubmit'); const onError = (errors, e) => alert('onError'); return ( Submit ); }; ``` ## Validate model This function will receive the model data if form validation is successful. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const ButtonWrapper = styled('div', { display: 'flex', flexDirection: 'row', gap: '$web.semantic.spacing.scale.sm', flexWrap: 'wrap', }); const form = useFormV2({ defaultValues: { firstName: 'John', }, }); const handleValidateFirst = () => { form.validate( 'firstName', (data) => { alert(`FormData: ${JSON.stringify(data)}`); }, (error) => { delete error.ref; alert(`Error: ${JSON.stringify(error)}`); } ); }; const handleValidateLast = () => { form.validate( 'lastName', (data) => { alert(`FormData: ${JSON.stringify(data)}`); }, (error) => { delete error.ref; alert(`Error: ${JSON.stringify(error)}`); } ); }; return ( Validate First Name Validate Last Name ); }; ``` ## Reset Reset either the entire form state or part of the form state. When invoking reset(\{ value \}) without supplying defaultValues via useForm, the library will replace defaultValues with a shallow clone value object that you provide (not deepClone). ```jsx // ❌ avoid the following with deep nested default values const defaultValues = { object: { deepNest: { file: new File() } } }; useFormV2({ defaultValues }); reset(defaultValues); // share the same reference // ✅ it's safer with the following, as we only doing shallow clone with defaultValues useFormV2({ deepNest: { file: new File() } }); reset({ deepNest: { file: new File() } }); ``` ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const ButtonWrapper = styled('div', { display: 'flex', flexDirection: 'row', gap: '$web.semantic.spacing.scale.sm', flexWrap: 'wrap', }); const form = useFormV2({ defaultValues: { firstName: 'John', lastName: 'Doe', }, }); const reset = () => { form.reset(); }; const resetWithValue = () => { form.reset({ firstName: 'John' }); }; const resetWithOptions = () => { form.reset( { lastName: 'Doe', }, { keepErrors: true, keepDirty: true, keepIsSubmitted: false, keepTouched: false, keepIsValid: false, keepSubmitCount: false, } ); }; return ( Reset Reset With Value Reset With Options ); }; ``` ## Set error The function allows you to manually set one or more errors. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const ButtonWrapper = styled('div', { display: 'flex', flexDirection: 'row', gap: '$web.semantic.spacing.scale.sm', flexWrap: 'wrap', }); const form = useFormV2({ defaultValues: { firstName: 'John', lastName: 'Doe', }, }); // Set single error const setSingleError = () => { form.setError('firstName', { type: 'manual', message: 'There is an error with your name!', }); }; // Set multiple errors const setMultipleErrors = () => { [ { type: 'manual', name: 'firstName', message: 'Check first name', }, { type: 'manual', name: 'lastName', message: 'Check last name', }, ].forEach(({ name, type, message }) => { form.setError(name, { type, message }); }); }; // Set error for single field errors React.useEffect(() => { form.setError('firstName', { types: { required: 'This is required', minLength: 'This is minLength', }, }); }, []); return ( setSingleError()}> Set Single Error setMultipleErrors()}> Set Multiple Errors ); }; ``` ## Clear errors This function can manually clear errors in the form. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const ButtonWrapper = styled('div', { display: 'flex', flexDirection: 'row', gap: '$web.semantic.spacing.scale.sm', flexWrap: 'wrap', }); const form = useFormV2({ defaultValues: { firstName: 'John', lastName: 'Doe', phone: '555-555-5555', }, }); const resetErrors = () => { [ { type: 'manual', name: 'firstName', message: 'Required', }, { type: 'manual', name: 'lastName', message: 'Required', }, { type: 'manual', name: 'phone', message: 'Required', }, ].forEach(({ name, type, message }) => { form.setError(name, { type, message }); }); }; // Clear single error const clearSingleErrors = () => { form.clearErrors('firstName'); }; // Clear multiple errors const clearMultipleErrors = () => { form.clearErrors(['firstName', 'lastName']); }; // Clear all errors const clearAllErrors = () => { form.clearErrors(); }; return ( resetErrors()} > Set Errors clearSingleErrors()}> Clear Single Error clearMultipleErrors()}> Clear Multiple Error clearAllErrors()}> Clear All Errors ); }; ``` ## Set value This function allows you to dynamically set the value of a registered field. At the same time, it tries to avoid unnecessary re-renders. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const ButtonWrapper = styled('div', { display: 'flex', flexDirection: 'row', gap: '$web.semantic.spacing.scale.sm', flexWrap: 'wrap', }); const form = useFormV2(); const setSingleValue = () => { form.setValue('firstName', 'Bob'); }; const setMultipleValues = () => { form.setValue('address', { street: '123 Main St', city: 'Anytown', state: 'CA', zip: '12345', }); }; const setValueWithOptions = () => { form.setValue('lastName', 'Luo', { shouldValidate: true, shouldDirty: true, }); }; return ( setSingleValue()}> Set Value setMultipleValues()}> Set Multiple Values setValueWithOptions()}> Set Value With Options ); }; ``` ## Set focus This method will allow users to programmatically focus on input. Make sure the input's ref is registered in the hook form. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); const setFocus = () => { form.setFocus('firstName'); }; return ( setFocus()} css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Set Focus ); }; ``` ## Get values An optimized helper for reading form values. The difference between watch and getValues is that getValues will not trigger re-renders or subscribe to input changes. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2({ defaultValues: { firstName: 'John', lastName: 'Doe', phone: '555-555-5555', }, }); // Read an individual field value by name const singleValue = form.getValues('firstName'); // Read multiple fields by name const multipleValues = form.getValues(['firstName', 'lastName']); // Reads all form values const allValues = form.getValues(); return (

Single value: {JSON.stringify(singleValue)}

Multiple values: {JSON.stringify(multipleValues)}

All values: {JSON.stringify(allValues)}

); }; ``` ## Trigger Manually triggers form or input validation. This method is also useful when you have dependent validation (input validation depends on another input's value). ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const ButtonWrapper = styled('div', { display: 'flex', flexDirection: 'row', gap: '$web.semantic.spacing.scale.sm', flexWrap: 'wrap', }); const form = useFormV2(); // Trigger one input to validate const triggerSingle = () => { form.trigger('firstName'); }; // Trigger multiple inputs to validate const triggerMultiple = () => { form.trigger(['firstName', 'lastName']); }; // Trigger entire form to validate const triggerAll = () => { form.trigger(); }; const clearErrors = () => { form.clearErrors(); }; return ( triggerSingle()}> Trigger Single triggerMultiple()}> Trigger Multiple triggerAll()}> Trigger All clearErrors()} > Clear Errors ); }; ``` ## Validation strategy There are two different validation strategies: - `mode`: Validation strategy before submitting (default: `onSubmit`). - `reValidateMode`: Validation strategy after submitting (default: `onChange`). Teams should only use the following options: - `mode`: `onChange` | `onSubmit` - `reValidateMode`: `onChange` | `onSubmit` **Disclaimer:** Using other validation strategies can lead to inconsistent behavior. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form1 = useFormV2(); const form2 = useFormV2({ mode: 'onChange', reValidateMode: 'onSubmit', }); const onSubmit = (data) => { console.log('data', data); }; return ( Submit Submit ); }; ``` ## Cross-field validation example ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); const onSubmit = (data) => { console.log('data', data); }; return ( { const checkValue = form.getValues('lastName-check'); if (!checkValue && !v) { return 'Required'; } }, }} /> { form.trigger('middleName'); }} /> Submit ); }; ``` ## Form input autofill ```jsx live () => { const form = useFormV2(); const inputs = [ { label: 'Title', autoComplete: 'honorific-prefix', }, { label: 'First Name', autoComplete: 'given-name', }, { label: 'Middle Name', autoComplete: 'additional-name', }, { label: 'Last Name', autoComplete: 'family-name', }, { label: 'Nickname', autoComplete: 'nickname', }, { label: 'Email', autoComplete: 'email', }, { label: 'Username', autoComplete: 'username', }, { label: 'Current Password', autoComplete: 'current-password', }, { label: 'New Password', autoComplete: 'new-password', }, { label: 'One Time Code', autoComplete: 'one-time-code', }, { label: 'Organization Title', autoComplete: 'organization-title', }, { label: 'Organization', autoComplete: 'organization', }, { label: 'Address', autoComplete: 'street-address', }, { label: 'Address Line 1', autoComplete: 'address-line1', }, { label: 'Address Line 2', autoComplete: 'address-line2', }, { label: 'Country', autoComplete: 'country', }, { label: 'Country Name', autoComplete: 'country-name', }, { label: 'Postal Code', autoComplete: 'postal-code', }, { label: 'Name on Credit Card', autoComplete: 'cc-name', }, { label: 'First Name on Credit Card', autoComplete: 'cc-given-name', }, { label: 'Middle Name on Credit Card', autoComplete: 'cc-additional-name', }, { label: 'Last Name on Credit Card', autoComplete: 'cc-family-name', }, { label: 'Credit Card Number', autoComplete: 'cc-number', }, { label: 'Credit Card Expiration Date', autoComplete: 'cc-exp', }, { label: 'Credit Card Expiration Month', autoComplete: 'cc-exp-month', }, { label: 'Credit Card Expiration Year', autoComplete: 'cc-exp-year', }, { label: 'Credit Card CSC Code', autoComplete: 'cc-csc', }, { label: 'Credit Card Type', autoComplete: 'cc-type', }, { label: 'Transation Currency', autoComplete: 'transaction-currency', }, { label: 'Transation Amount', autoComplete: 'transaction-amount', }, { label: 'Birth Date', autoComplete: 'bday', }, { label: 'Birth Day', autoComplete: 'bday-day', }, { label: 'Birth Month', autoComplete: 'bday-month', }, { label: 'Birth Year', autoComplete: 'bday-year', }, { label: 'Gender', autoComplete: 'sex', }, { label: 'Phone Number', autoComplete: 'tel', }, ]; const handleSubmit = (data) => { console.log('data', data); }; return ( {inputs.map((item) => { return (

); })} Submit ); }; ``` ## Autofill off ```jsx live () => { const form = useFormV2(); const handleSubmit = (data) => { console.log('data', data); }; return ( Submit ); }; ``` ## Additional documentation `@uhg-abyss/web/hooks/useFormV2` is a built on top of the `useForm` hook from React Form Hook. Teams that already leverage or want to use React Hook Form in other spots in your application can use the `@uhg-abyss/web/tools/reactHookFormTools` package. This package can ensure you are using the same version of React Hook Form across your application and can also be used to grab type information directly. Here is an example below: **Note: ** You should be using Abyss's `useFormV2` hook when using Abyss componenets and **not** react hook forms. ```tsx import { SubmitHandler } from '@uhg-abyss/web/tools/reactHookFormTools'; interface FormData { firstName: string; } ///... const handleSubmit: SubmitHandler = (data) => { console.log('data', data); }; ///... ``` Using TypeScript with `useFormV2` gives you strong type checking for your form data structure. Here's a example: ```tsx interface FormData { firstName: string; lastName: string; } const form = useFormV2({ defaultValues: { firstName: '', lastName: '', pizza: 'cheese', // Throws TS error since pizza is not a field in FormData }, }); // Throws TS error since pizza is not a field in FormData const WatchField = form.watch('pizza'); // Doesn't throw TS error since firstName and lastName are fields in FormData const WatchFields = form.watch(['firstName', 'lastName']); ``` --- id: use-form category: State Management title: useForm description: useForm is a hook for defining, validating and submitting forms. pagination_prev: web/hooks/use-form-v2 pagination_next: web/hooks/use-form-field-Array subDirectory: useForm/v1 --- ```jsx import { useForm } from '@uhg-abyss/web/hooks/useForm'; ``` ## Usage ```jsx live () => { const form = useForm(); const onSubmit = (data) => { // Do something on submit alert(`FormData: ${JSON.stringify(data)}`); }; return ( ); }; ``` ## Default values The defaultValues prop populates the entire form with default values. It supports both synchronous and asynchronous assignments of default values. ```jsx live () => { // Default Values Passed into useForm const form = useForm({ defaultValues: { firstName: 'John', lastName: 'Doe', }, }); const onSubmit = (data) => { alert(`FormData: ${JSON.stringify(data)}`); }; return ( ); }; ``` ## Values The values props will react to changes and update the form values, which is useful when your form needs to be updated by external state or server data. ```jsx // set default value sync function App({ values }) { useForm({ values, // will get updated when values props updates }); } function App() { const values = useFetch('/api'); useForm({ defaultValues: { firstName: '', lastName: '', }, values, // will get updated once values returns }); } ``` ## Form state This object contains information about the form state. If you want to subscribe to formState via useEffect, make sure that you place the entire formState in the optional array. ```jsx const form = useForm(); const { errors, // An object with field errors isDirty, // Set to true after the user modifies any of the inputs. isValid, // Set to true if the form doesn't have any errors. isValidating, // Set to true during validation. isSubmitting, // true if the form is currently being submitted; false if otherwise. isSubmitted, // Set to true after the form is submitted. isSubmitSuccessful, // Indicate the form was successfully submitted without any Promise rejection or Error being thrown within the handleSubmit callback. submitCount, // Number of times the form was submitted. touchedFields, // An object containing all the inputs the user has interacted with. dirtyFields, // An object with the user-modified fields. } = form.formState; ``` ## Watch This will watch specified inputs and return their values. It is useful for determining what to render. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { alert(`FormData: ${JSON.stringify(data)}`); }; // Watch one field const WatchField = form.watch('firstName'); // Target specific fields by their names const WatchFields = form.watch(['firstName', 'lastName']); // Watch everything by passing no arguments const WatchAllFields = form.watch(); return (

Watch One Field: {JSON.stringify(WatchField)}

Watch Multiple Fields: {JSON.stringify(WatchFields)}

Watch All Fields: {JSON.stringify(WatchAllFields)}

); }; ``` ## Handle submit This function will receive the form data if form validation is successful. ```jsx live () => { const form = useForm({ defaultValues: { firstName: 'John', lastName: 'Doe', }, }); const onSubmit = (data, e) => alert('onSubmit'); const onError = (errors, e) => alert('onError'); return ( ); }; ``` ## Validate model This function will receive the model data if form validation is successful. ```jsx live () => { const form = useForm({ defaultValues: { firstName: 'John', }, }); const handleValidateFirst = () => { form.validate( 'firstName', (data) => { alert(`FormData: ${JSON.stringify(data)}`); }, (error) => { delete error.ref; alert(`Error: ${JSON.stringify(error)}`); } ); }; const handleValidateLast = () => { form.validate( 'lastName', (data) => { alert(`FormData: ${JSON.stringify(data)}`); }, (error) => { delete error.ref; alert(`Error: ${JSON.stringify(error)}`); } ); }; return ( ); }; ``` ## Reset Reset either the entire form state or part of the form state. When invoking reset(\{ value \}) without supplying defaultValues via useForm, the library will replace defaultValues with a shallow clone value object that you provide (not deepClone). ```jsx // ❌ avoid the following with deep nested default values const defaultValues = { object: { deepNest: { file: new File() } } }; useForm({ defaultValues }); reset(defaultValues); // share the same reference // ✅ it's safer with the following, as we only doing shallow clone with defaultValues useForm({ deepNest: { file: new File() } }); reset({ deepNest: { file: new File() } }); ``` ```jsx live () => { const form = useForm({ defaultValues: { firstName: 'John', lastName: 'Doe', }, }); const reset = () => { form.reset(); }; const resetWithValue = () => { form.reset({ firstName: 'John' }); }; const resetWithOptions = () => { form.reset( { lastName: 'Doe', }, { keepErrors: true, keepDirty: true, keepIsSubmitted: false, keepTouched: false, keepIsValid: false, keepSubmitCount: false, } ); }; return ( ); }; ``` ## Set error The function allows you to manually set one or more errors. ```jsx live () => { const form = useForm({ defaultValues: { firstName: 'John', lastName: 'Doe', }, }); // Set single error const setSingleError = () => { form.setError('firstName', { type: 'manual', message: 'There is an error with your name!', }); }; // Set multiple errors const setMultipleErrors = () => { [ { type: 'manual', name: 'firstName', message: 'Check first name', }, { type: 'manual', name: 'lastName', message: 'Check last name', }, ].forEach(({ name, type, message }) => { form.setError(name, { type, message }); }); }; // Set error for single field errors React.useEffect(() => { form.setError('firstName', { types: { required: 'This is required', minLength: 'This is minLength', }, }); }, []); return ( ); }; ``` ## Clear errors This function can manually clear errors in the form. ```jsx live () => { const form = useForm({ defaultValues: { firstName: 'John', lastName: 'Doe', phone: '555-555-5555', }, }); const resetErrors = () => { [ { type: 'manual', name: 'firstName', message: 'Required', }, { type: 'manual', name: 'lastName', message: 'Required', }, { type: 'manual', name: 'phone', message: 'Required', }, ].forEach(({ name, type, message }) => { form.setError(name, { type, message }); }); }; // Clear single error const clearSingleErrors = () => { form.clearErrors('firstName'); }; // Clear multiple errors const clearMultipleErrors = () => { form.clearErrors(['firstName', 'lastName']); }; // Clear all errors const clearAllErrors = () => { form.clearErrors(); }; return ( ); }; ``` ## Set value This function allows you to dynamically set the value of a registered field. At the same time, it tries to avoid unnecessary re-renders. ```jsx live () => { const form = useForm(); const setSingleValue = () => { form.setValue('firstName', 'Bob'); }; const setMultipleValues = () => { form.setValue('address', { street: '123 Main St', city: 'Anytown', state: 'CA', zip: '12345', }); }; const setValueWithOptions = () => { form.setValue('lastName', 'Luo', { shouldValidate: true, shouldDirty: true, }); }; return ( ); }; ``` ## Set focus This method will allow users to programmatically focus on input. Make sure the input's ref is registered in the hook form. ```jsx live () => { const form = useForm(); const setFocus = () => { form.setFocus('firstName'); }; return ( ); }; ``` ## Get values An optimized helper for reading form values. The difference between watch and getValues is that getValues will not trigger re-renders or subscribe to input changes. ```jsx live () => { const form = useForm({ defaultValues: { firstName: 'John', lastName: 'Doe', phone: '555-555-5555', }, }); // Read an individual field value by name const singleValue = form.getValues('firstName'); // Read multiple fields by name const multipleValues = form.getValues(['firstName', 'lastName']); // Reads all form values const allValues = form.getValues(); return (

Single Value: {JSON.stringify(singleValue)}

Multiple Values: {JSON.stringify(multipleValues)}

All Values: {JSON.stringify(allValues)}

); }; ``` ## Trigger Manually triggers form or input validation. This method is also useful when you have dependent validation (input validation depends on another input's value). ```jsx live () => { const form = useForm(); // Trigger one input to validate const triggerSingle = () => { form.trigger('firstName'); }; // Trigger multiple inputs to validate const triggerMultiple = () => { form.trigger(['firstName', 'lastName']); }; // Trigger entire form to validate const triggerAll = () => { form.trigger(); }; const clearErrors = () => { form.clearErrors(); }; return ( ); }; ``` ## Validation strategy There are two different validation strategies: - `mode`: Validation strategy before submitting (default: `onSubmit`). - `reValidateMode`: Validation strategy after submitting (default: `onChange`). Teams should only use the following options: - `mode`: `onChange` | `onSubmit` - `reValidateMode`: `onChange` | `onSubmit` **Disclaimer:** Using other validation strategies can lead to inconsistent behavior. ```jsx live () => { const form1 = useForm(); const form2 = useForm({ mode: 'onChange', reValidateMode: 'onSubmit', }); const onSubmit = (data) => { console.log('data', data); }; return ( ); }; ``` ## Cross-field validation example ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( { const checkValue = form.getValues('lastName-check'); if (!checkValue && !v) { return 'Required'; } }, }} /> { form.trigger('middleName'); }} /> ); }; ``` ## Form input autofill ```jsx live () => { const form = useForm(); const inputs = [ { label: 'Title', autoComplete: 'honorific-prefix', }, { label: 'First Name', autoComplete: 'given-name', }, { label: 'Middle Name', autoComplete: 'additional-name', }, { label: 'Last Name', autoComplete: 'family-name', }, { label: 'Nickname', autoComplete: 'nickname', }, { label: 'Email', autoComplete: 'email', }, { label: 'Username', autoComplete: 'username', }, { label: 'Current Password', autoComplete: 'current-password', }, { label: 'New Password', autoComplete: 'new-password', }, { label: 'One Time Code', autoComplete: 'one-time-code', }, { label: 'Organization Title', autoComplete: 'organization-title', }, { label: 'Organization', autoComplete: 'organization', }, { label: 'Address', autoComplete: 'street-address', }, { label: 'Address Line 1', autoComplete: 'address-line1', }, { label: 'Address Line 2', autoComplete: 'address-line2', }, { label: 'Country', autoComplete: 'country', }, { label: 'Country Name', autoComplete: 'country-name', }, { label: 'Postal Code', autoComplete: 'postal-code', }, { label: 'Name on Credit Card', autoComplete: 'cc-name', }, { label: 'First Name on Credit Card', autoComplete: 'cc-given-name', }, { label: 'Middle Name on Credit Card', autoComplete: 'cc-additional-name', }, { label: 'Last Name on Credit Card', autoComplete: 'cc-family-name', }, { label: 'Credit Card Number', autoComplete: 'cc-number', }, { label: 'Credit Card Expiration Date', autoComplete: 'cc-exp', }, { label: 'Credit Card Expiration Month', autoComplete: 'cc-exp-month', }, { label: 'Credit Card Expiration Year', autoComplete: 'cc-exp-year', }, { label: 'Credit Card CSC Code', autoComplete: 'cc-csc', }, { label: 'Credit Card Type', autoComplete: 'cc-type', }, { label: 'Transation Currency', autoComplete: 'transaction-currency', }, { label: 'Transation Amount', autoComplete: 'transaction-amount', }, { label: 'Birth Date', autoComplete: 'bday', }, { label: 'Birth Day', autoComplete: 'bday-day', }, { label: 'Birth Month', autoComplete: 'bday-month', }, { label: 'Birth Year', autoComplete: 'bday-year', }, { label: 'Gender', autoComplete: 'sex', }, { label: 'Phone Number', autoComplete: 'tel', }, ]; const handleSubmit = (data) => { console.log('data', data); }; return ( {inputs.map((item) => { return (

); })} ); }; ``` ## Autofill off ```jsx live () => { const form = useForm(); const handleSubmit = (data) => { console.log('data', data); }; return ( ); }; ``` ## Additional documentation `@uhg-abyss/web/hooks/useForm` is a built on top of the `useForm` hook from React Form Hook. Teams that already leverage or want to use React Hook Form in other spots in your application can use the `@uhg-abyss/web/tools/reactHookFormTools` package. This package can ensure you are using the same version of React Hook Form across your application and can also be used to grab type information directly. Here is an example below: **Note: ** You should be using Abyss's `useForm` hook when using Abyss componenets and **not** react hook forms. ```tsx import { SubmitHandler } from '@uhg-abyss/web/tools/reactHookFormTools'; interface FormData { firstName: string; } ///... const handleSubmit: SubmitHandler = (data) => { console.log('data', data); }; ///... ``` --- id: use-form-field-Array category: State Management title: useFormFieldArray description: The useFormFieldArray is custom hook for working with uncontrolled Field Arrays (dynamic inputs). This hook supplies you with functions for manipulating the array/list of fields. pagination_prev: web/hooks/use-form pagination_next: web/hooks/use-overlay --- ```jsx import { useFormFieldArray } from '@uhg-abyss/web/hooks/useFormFieldArray'; ``` ## Usage ```jsx live () => { const defaultFormValues = { data: [{ firstName: 'Bill', lastName: 'Lou' }], }; const replaceFormValues = [ { firstName: 'replaceBill', lastName: 'replaceLou' }, { firstName: 'replaceBill-2', lastName: 'replaceLou-2' }, ]; const form = useForm({ defaultValues: defaultFormValues, }); const { fields, append, prepend, insert, swap, move, replace, remove } = useFormFieldArray({ control: form.control, name: 'data', }); const handleSubmit = (data) => { console.log('Submitted', data); }; return ( {fields.map((field, index) => { return (

Row #{index + 1}

); })} ); }; ``` ## Fields This object contains the defaultValue and key for all your inputs. It's important to assign defaultValue to the inputs. - The field.id (and not index) must be added as the component key to prevent re-renders breaking the fields. ```jsx // ✅ correct: {fields.map((field, index) => (

))} // ✅ correct: {fields.map((field, index) => )} // ❌ incorrect: {fields.map((field, index) => )} ```
- useFieldArray automatically generates a unique identifier named id which is used for key prop. For more information why this is required: React lists and keys.

When your array field contains objects with the key name id, useFieldArray will overwrite and remove it. If you want to keep the id field in your array of objects, you must use keyName prop to change to other name. Refer to the following example: ```jsx const { fields } = useFieldArray({ keyName: 'key', // by default key name is id, and input value with name id will be omitted }); { fields.map((field, index) => (

// key name changed // input value id will be retained

)); } ```
- When you append, prepend, insert and update the field array, the obj can't be empty object rather need to supply all your input's defaultValues. ```jsx append(); ❌ append({}); ❌ append({ firstName: 'bill', lastName: 'luo' }); ✅ ``` ## Append Use the `append()` function to append input/inputs to the end of your fields and focus. ```jsx live () => { const defaultFormValues = { append: [{ firstName: 'Bill', lastName: 'Lou' }], }; const form = useForm({ defaultValues: defaultFormValues, }); const { fields, append } = useFormFieldArray({ control: form.control, name: 'append', }); const handleSubmit = (data) => { console.log('Submitted', data); }; return ( {fields.map((field, index) => { return (

Row #{index + 1}

); })} ); }; ``` ## Prepend Use the `prepend()` function to prepend input/inputs to the start of your fields and focus. ```jsx live () => { const defaultFormValues = { prepend: [{ firstName: 'Bill', lastName: 'Lou' }], }; const form = useForm({ defaultValues: defaultFormValues, }); const { fields, prepend } = useFormFieldArray({ control: form.control, name: 'prepend', }); const handleSubmit = (data) => { console.log('Submitted', data); }; return ( {fields.map((field, index) => { return (

Row #{index + 1}

); })} ); }; ``` ## Insert Use the `insert()` function to insert input/inputs at particular position and focus. ```jsx live () => { const defaultFormValues = { insert: [ { firstName: 'Bill', lastName: 'Lou' }, { firstName: 'Bill-2', lastName: 'Lou-2' }, ], }; const form = useForm({ defaultValues: defaultFormValues, }); const { fields, insert, remove } = useFormFieldArray({ control: form.control, name: 'insert', }); const handleSubmit = (data) => { console.log('Submitted', data); }; return ( {fields.map((field, index) => { return (

Row #{index + 1}

); })} ); }; ``` ## Swap Use the `swap()` function to swap input/inputs position. ```jsx live () => { const defaultFormValues = { swap: [ { firstName: 'Bill', lastName: 'Lou' }, { firstName: 'swapBill', lastName: 'swapLou' }, ], }; const form = useForm({ defaultValues: defaultFormValues, }); const { fields, swap, remove } = useFormFieldArray({ control: form.control, name: 'swap', }); const handleSubmit = (data) => { console.log('Submitted', data); }; return ( {fields.map((field, index) => { return (

Row #{index + 1}

); })} ); }; ``` ## Move Use the `move()` function to move input/inputs to another position. ```jsx live () => { const defaultFormValues = { move: [ { firstName: 'Bill', lastName: 'Lou' }, { firstName: 'moveBill', lastName: 'moveLou' }, ], }; const form = useForm({ defaultValues: defaultFormValues, }); const { fields, move } = useFormFieldArray({ control: form.control, name: 'move', }); const handleSubmit = (data) => { console.log('Submitted', data); }; return ( {fields.map((field, index) => { return (

Row #{index + 1}

); })} ); }; ``` ## Replace Use the `replace()` function to replace the entire field array values with a custom list of objects. ```jsx live () => { const replaceFormValues = [ { firstName: 'replaceBill', lastName: 'replaceLou' }, { firstName: 'replaceBill-2', lastName: 'replaceLou-2' }, ]; const defaultFormValues = { data: [ { firstName: 'Bill', lastName: 'Lou' }, { firstName: 'Bill-2', lastName: 'Lou-2' }, ], }; const form = useForm({ defaultValues: defaultFormValues, }); const { fields, replace } = useFormFieldArray({ control: form.control, name: 'data', }); const handleSubmit = (data) => { console.log('Submitted', data); }; return ( {fields.map((field, index) => { return (

Row #{index + 1}

); })} ); }; ``` ## Remove Use the `remove()` function to remove elements at a particular position (or positions) in the list, or remove all of them when no index is provided. ```jsx live () => { const defaultFormValues = { remove: [ { firstName: 'removeBill', lastName: 'removeLou' }, { firstName: 'removeBill-2', lastName: 'removeLou-2' }, { firstName: 'removeBill-3', lastName: 'removeLou-3' }, ], }; const form = useForm({ defaultValues: defaultFormValues, }); const { fields, remove } = useFormFieldArray({ control: form.control, name: 'remove', }); const handleSubmit = (data) => { console.log('Submitted', data); }; return ( {fields.map((field, index) => { return (

Row #{index + 1}

); })} ); }; ``` ## Additional documentation This hook is a renaming of the useFieldArray hook from React Form Hook. If you would like to see a more detailed description for the usage of this hook, you can view the documentation here. --- id: use-fuse category: UI & DOM title: useFuse description: The useFuse hook is used to help with fuzzy search, also known as approximate string matching. pagination_prev: web/hooks/use-collapse pagination_next: web/hooks/use-horizontal-scroll --- ```jsx import { useFuse } from '@uhg-abyss/web/hooks/useFuse'; ``` ## Usage The `useFuse` hook uses the Fuse.js library to help with fuzzy searching (more formally known as approximate string matching), which is the technique of finding strings that are approximately equal to a given pattern (rather than exactly). ## Example with TextInput component ```jsx live () => { const [value, setValue] = useState(''); const keys = ['title', 'author']; const totalList = [ { title: "Old Man's War", author: 'John Scalzi', }, { title: 'The Lock Artist', author: ' Steve Hamilton', }, { title: 'HTML5', author: 'Remy Sharp', }, { title: 'Right Ho Jeeves', author: 'P.D Woodhouse', }, { title: 'The Code of the Wooster', author: 'P.D Woodhouse', }, { title: 'Thank You Jeeves', author: 'P.D Woodhouse', }, { title: 'The DaVinci Code', author: 'Dan Brown', }, { title: 'Angels & Demons', author: 'Dan Brown', }, { title: 'The Silmarillion', author: 'J.R. Tolkien', }, { title: 'Syrup', author: 'Max Barry', }, { title: 'The Lost Symbol', author: 'Dan Brown', }, { title: 'The Book of Lies', author: 'Brad Meltzer', }, { title: 'Lamb', author: 'Christopher Moore', }, ]; const fuse = useFuse({ list: totalList, config: { threshold: 0.4, }, keys, }); return ( setValue(e.target.value)} onClear={() => setValue('')} placeholder="Enter search value" /> Search Results: {JSON.stringify(fuse.search(value), null, 2)} ); }; ``` ## Fuse keys Fuse Keys are a list of keys that will be searched. Keys can be used to search in an object array, a nested search, as well as a weighted search. When a weight isn't provided, it will default to 1. ## Fuse config options Listed below are options that can be added to the config provided by the Fuse.js library ### Basic options - **isCaseSensitive**: type boolean, default set to false - **includeScore**: type boolean, default set to false - **includeMatches**: type boolean, default set to false - **minMatchCharLength**: type number, default set to 1 - **shouldSort**: type boolean, default set to true - **findAllMatches**: type boolean, default set to false - **keys**: type Array, default set to empty array ### Fuzzy matching options - **location**: type number, default is set to 0 - **threshold**: type number, default is set to 0.6 - **distance**: type number, default is set to 100 - **ignoreLocation**: type boolean, default is set to false ### Advanced options - **getFn**: type Function, default (obj: T, path: string | string[]) => string | string[] ## Search object array example ```jsx const list = [ { title: "Old Man's War", author: 'John Scalzi', tags: ['fiction'], }, { title: 'The Lock Artist', author: 'Steve', tags: ['thriller'], }, ]; const config = { includeScore: true, }; const keys= ['author', 'tags'], const fuse = useFuse({list, config, keys}); const result = fuse.search('tion'); ``` Expected Output: ```jsx [ { item: { title: "Old Man's War", author: 'John Scalzi', tags: ['fiction'], }, refIndex: 0, score: 0.03, }, ]; ``` ## Nested search example You can search through nested values using dot notation, array notation, or by defining a per-key `getFN` function. It is important to note that the path has to point to a string, otherwise you will not get any results. Example with Dot Notation: ```jsx const list = [ { title: "Old Man's War", author: { name: 'John Scalzi', tags: [ { value: 'American', }, ], }, }, { title: 'The Lock Artist', author: { name: 'Steve Hamilton', tags: [ { value: 'English', }, ], }, }, ]; const config = { includeScore: true, }; const keys = ['author.tags.value']; const fuse = useFuse({ list, config, keys }); const result = fuse.search('engsh'); ``` Using getFN: ```jsx const config = { includeScore: true, }; const keys = [ { name: 'title', getFn: (book) => book.title }, { name: 'authorName', getFn: (book) => book.author.name }, ]; const fuse = useFuse({ list, config, keys }); const result = fuse.search({ authorName: 'Steve' }); ``` Expected output for both: ```jsx [ { item: { title: 'The Lock Artist', author: { name: 'Steve Hamilton', tags: [ { value: 'English', }, ], }, }, refIndex: 1, score: 0.4, }, ]; ``` ## Properties ```typescript useFuse({ list, config, keys }); ``` --- id: use-horizontal-scroll category: UI & DOM title: useHorizontalScroll description: Custom management of responsive horizontal scroll compatible components. pagination_prev: web/hooks/use-fuse pagination_next: web/hooks/use-media-query --- ```jsx import { useHorizontalScroll } from '@uhg-abyss/web/hooks/useHorizontalScroll'; ``` ## Overview `useHorizontalScroll` provides the ability to apply custom configurations to the responsive horizontal scroll handling of compatible components. See the following links for examples on how to implement horizontal scroll within compatible components: - [NavMenuPrimitives](#nav-menu-primitives) - [StepIndicator](#step-indicator) NOTE: The name of the component utilizing this hook must be provided to the `component` prop for built in accessibility features to be applied (see examples below). ## Scroll buttons Use the `leftButton` and `rightButton` props to apply the following custom configurations to the default supplied scroll buttons: - **displayThreshold**: percentage of left or right most item that needs to be in view before button displays; default is `.75` - **offset**: adjust the alignment of items after clicking the right or left scroll button - **useButtonOffset**: uses the button width for aligning scroll items; should only be used when buttons are positioned over the top of the scroll container - **icon**: apply a custom [material icon](/web/ui/icon-material?tab=material+icons); default is set per component - **ariaLabel**: supply custom aria-label to button; default is "Scroll Left" / "Scroll Right" ### Scroll duration Use the `scrollDuration` prop to set the scrolling speed in ms. The default value is `900`. ### Scroll threshold Use the `scrollThreshold` prop to determine what percentage of the left or right-most item must be in view before it will scroll to the previous or next item. Default is `.75`. If the percentage of the item in view is under the threshold, clicking the scroll button will scroll that item fully into view. ## Usage examples ### Step indicator To enable horizontal scroll, pass the `horizontalScroll` prop to `` and supply to it your custom configuration returned from useHorizontalScroll. If horizontalScroll is applied and no configuartion is supplied it will utilize the default scroll design and behavior. ```jsx live () => { const [isChecked, setChecked] = useState(false); const commonStyles = { 'abyss-step-indicator-root': { '.abyss-step-indicator-step-root': { minWidth: '150px' }, }, }; const StepIndicatorDefault = () => { return ( ); }; const StepIndicatorCustom = () => { const commonOverlayStyles = { content: '', position: 'absolute', zIndex: 5, height: '60px', width: '60px', }; const scrollConfig = useHorizontalScroll({ component: 'StepIndicator', // must be provided for built in accessibility features to be applied scrollDuration: 1200, scrollThreshold: 0.5, leftButton: { displayThreshold: 1, // displays immediately once scrolled icon: 'arrow_circle_left', offset: 50, // shifts 50px to the left of step item after clicking scroll button ariaLabel: 'Scroll to previous step', }, rightButton: { displayThreshold: 1, // displays immediately once scrolled icon: 'arrow_circle_right', offset: 50, // shifts 50px to the right of step item after clicking scroll button ariaLabel: 'Scroll to next step', }, css: { 'abyss-step-indicator-scroll-button-left': { position: 'relative', '&:before': { ...commonOverlayStyles, left: '30px', background: 'linear-gradient(to right, $white, transparent)', }, }, 'abyss-step-indicator-scroll-button-right': { position: 'relative', '&:before': { ...commonOverlayStyles, right: '30px', background: 'linear-gradient(to left, $white, transparent)', }, }, }, }); return ( ); }; return ( {isChecked ? : } setChecked(e.target.checked)} /> ); }; ``` ### Nav Menu Primitives To enable horizontal scroll, you must wrap your Nav Menu Primitive components with `NavMenuPrimitives.Provider`. Add the `scrollState` prop to supply your custom configuration returned from useHorizontalScroll. ```jsx live () => { const [isChecked, setChecked] = useState(false); const DropdownMenuContent = ( CSS-in-JS with best-in-class developer experience. ); const NavMenu = ( Sample Link console.log('Sample onClick clicked')} > Sample onClick {DropdownMenuContent} Dropdown Menu 1 Dropdown Menu 2 {DropdownMenuContent} Dropdown Menu 3 {DropdownMenuContent} ); const NavMenuDefault = () => { return {NavMenu}; }; const NavMenuCustom = () => { const scrollState = useHorizontalScroll({ component: 'NavMenuPrimitives', // must be provided for built in accessibility features to be applied scrollDuration: 1200, scrollThreshold: 0.5, leftButton: { displayThreshold: 1, // displays immediately once scrolled icon: 'arrow_circle_left', offset: 50, // shifts 50px to the left of menu item after clicking scroll button ariaLabel: 'Scroll to previous menu item', }, rightButton: { displayThreshold: 0.5, // displays once only 50% of right most item is in view icon: 'arrow_circle_right', offset: 50, // shifts 50px to the right of menu item after clicking scroll button ariaLabel: 'Scroll to next menu item', }, css: { 'abyss-nav-menu-scroll-button-left-icon': { height: '28px', width: '28px', }, 'abyss-nav-menu-scroll-button-right-icon': { height: '28px', width: '28px', }, }, }); return ( {NavMenu} ); }; return ( {isChecked ? : } setChecked(e.target.checked)} /> ); }; ``` --- id: use-media-query category: UI & DOM title: useMediaQuery description: Subscribe to media queries with window.matchMedia pagination_prev: web/hooks/use-horizontal-scroll pagination_next: web/hooks/use-scroll-trigger --- ```jsx import { useMediaQuery } from '@uhg-abyss/web/hooks/useMediaQuery'; ``` ## Usage The `useMediaQuery` hook leverages the window.matchMedia() API and will return false if api is not available unless initial value is provided in the second argument. Resize browser window to trigger window.matchMedia event: ```jsx live () => { const matches = useMediaQuery('(min-width: 900px)'); return ( Breakpoint {matches ? 'matches' : 'does not match'} ); }; ``` ## Server side rendering If you are using server side rendering the `useMediaQuery` hook will always return false as the window.matchMedia api is not available. To overcome this, you can override the initial value. ```javascript const matches = useMediaQuery('(max-width: 700px)', true, { getInitialValueInEffect: false, }); ``` ## Properties ```typescript useMediaQuery( query: string, initialValue?: boolean, options?: { getInitialValueInEffect: boolean; } ): boolean; ``` --- id: use-overlay category: State Management title: useOverlay description: A custom hook for managing overlays like Modal and Drawer with ease. sourceIsTS: true --- ```jsx import { useOverlay } from '@uhg-abyss/web/hooks/useOverlay'; ``` ## Usage Use the `useOverlay` hook to handle the state of any overlay like [V2ModalDialog](/web/ui/modal-dialog-v2) and [Drawer](/web/ui/drawer). Each overlay must have a unique `model` value to identify it, which must also be passed to the `useOverlay` hook. `useOverlay` returns an object with the following methods: - `open(data?: any)`: Opens the overlay. You can pass data to be injected into the overlay state. - `close(data?: any)`: Closes the overlay. You can pass data to be injected into the overlay state. - `toggle(data?: any)`: Toggles the overlay. You can pass data to be injected into the overlay state. - `getState()`: Returns the current state of the overlay. TypeScript users can provide a type for the state `data` to the `useOverlay` hook like so: ```ts interface ModalData { firstName: string; lastName: string; } const modal = useOverlay('data-modal'); modal.open({ firstName: 'John', lastName: 'Doe' }); // data parameter is now typed as ModalData ``` ```jsx live () => { const StateOutput = styled('pre', { marginTop: '8px', }); const model = 'data-modal'; const modal = useOverlay(model); const { isOpen, data } = modal.getState(); return ( modal.open({ firstName: 'John', lastName: 'Doe' })} aria-haspopup="dialog" > Open Modal Dialog {JSON.stringify({ isOpen, data }, null, 2)}

First Name: {data && data.firstName}

Last Name: {data && data.lastName}

); }; ``` ## OverlayProvider Applications must be wrapped in an [OverlayProvider](/web/ui/overlay-provider) in order to use `useOverlay`. ```jsx {children} ``` --- id: use-pagination-v2 category: State Management title: usePaginationV2 description: The usePagination is a custom hook for pagination capability. pagination_prev: web/hooks/use-overlay pagination_next: web/hooks/use-pagination subDirectory: usePagination/v2 sourceIsTS: true --- ```jsx import { usePaginationV2 } from '@uhg-abyss/web/hooks/usePagination'; ``` ```jsx live () => { const paginationProps = usePaginationV2({ pages: 6 }); return ( Page: {paginationProps.state.currentPage} Previous Next

        {JSON.stringify(paginationProps, null, 2)}

); }; ``` ## usePaginationV2 props ```jsx const pagination = usePaginationV2({ pages: 10 }); const { canNextPage, // Boolean to check if next page can be accessed canPreviousPage, // Boolean to check if previous page can be accessed goToPage, // Method to go to a certain page nextPage, // Method to go to next page lastPage, // Method to go to last page firstPage, // Method to go to first page pageCount, // Method to go to a certain page pageIndex, // Index of current page previousPage, // Method to go to a previous page setData, // Function to set active data state, // Includes currentPage, pageIndex, pageCount, rows, rowCount } = pagination; ``` ## Methods `previousPage`, `goToPage`, and `nextPage` are methods to let pagination know how to navigate to certain pages. ```jsx live () => { const { goToPage, previousPage, nextPage, state, ...paginationProps } = usePaginationV2({ pages: 10, }); const { currentPage } = state; return ( Page {currentPage} ); }; ``` ## Boolean checks `canPreviousPage` and `canNextPage` are used to check if the previous or next page is accessible given the current page index. ```jsx live () => { const { canPreviousPage, canNextPage, state, ...paginationProps } = usePaginationV2({ pages: 10 }); const { currentPage, pageCount } = state; return ( Page {currentPage} ); }; ``` ## Step tracker use case Use the `usePaginationV2` hook to handle the state and props of pagination. Methods returned include `setData`, `goToPage`, `previousPage`, and `nextPage`. Find additional resources on how usePaginationV2 can be used to support Step Tracker in the [Step Tracker](/web/ui/step-tracker-v2) page. ```jsx live () => { const paginationProps = usePaginationV2({ pages: 7, start: 2 }); return ( <>

        {JSON.stringify(paginationProps, null, 2)}

Previous Next ); }; ``` --- id: use-pagination category: State Management title: usePagination description: The usePagination is a custom hook for pagination capability. pagination_prev: web/hooks/use-pagination-v2 pagination_next: web/hooks/use-print subDirectory: usePagination/v1 --- ```jsx import { usePagination } from '@uhg-abyss/web/hooks/usePagination'; ``` ```jsx live () => { const paginationProps = usePagination({ pages: 6 }); return ( Page: {paginationProps.state.currentPage}

        {JSON.stringify(paginationProps, null, 2)}

); }; ``` ## usePagination props ```jsx const pagination = usePagination({ pages: 10 }); const { canNextPage, // Boolean to check if next page can be accessed canPreviousPage, // Boolean to check if previous page can be accessed gotoPage, // Method to go to a certain page nextPage, // Method to go to next page lastPage, // Method to go to last page firstPage, // Method to go to first page pageCount, // Method to go to a certain page pageIndex, // Index of current page previousPage, // Method to go to a previous page setData, // Function to set active data state, // Includes currentPage, pageIndex, pageCount, rows, rowCount } = pagination; ``` ## Step indicator use case Use the `usePagination` hook to handle the state and props of pagination. Methods returned include `setData`, `gotoPage`, `previousPage`, and `nextPage`. Find additional resources on how usePagination can be used to support Step Indicator in the [Step Indicator](/web/ui/step-indicator) page. ```jsx live () => { const paginationProps = usePagination({ pages: 7, start: 2 }); return ( <>

        {JSON.stringify(paginationProps, null, 2)}

); }; ``` --- id: use-print category: State Management title: usePrint description: The usePrint is a custom hook for managing how people can print your pages/save them to pdfs. pagination_prev: web/hooks/use-pagination pagination_next: web/hooks/use-query --- ```jsx import { usePrint } from '@uhg-abyss/web/hooks/usePrint'; ``` ```jsx render ``` ## Usage - `printPage()` is a function provided by usePrint that will open the print window and takes in two optional arguments, which are a callback function as the first argument and an object as the second with the `openNewWindow` prop. - `openNewWindow` prop can either be a boolean or a string - When set to `true` it will open a new blank window. - Alternatively you can pass in a string indicating the URL or path of the resource to be loaded within the new window. When providing a url it must share the same origin as the parent window. - The default value is `false`. ```jsx const callback = () => { console.log('print is complete'); }; printPage(callback, { openNewWindow: true, // default value is false }); ``` - `savePDF()` is a function provided by usePrint that will save your page as a PDF to your device and takes in two optional arguments, which are a callback function as the first argument that returns the PDF file object and an object as the second with the `config` prop. Please visit here to see PDF configuration options that can be passed into the `config` prop. ```jsx const callback = (pdf) => { console.log('pdf', pdf); }; savePDF(callback, { config: { margin: [2, 0], // default margin filename: `${document.title.split(' ').join('')}.pdf`, // default filename }, }); ``` - `createPDF()` is a function provided by usePrint that will create a PDF file object. It takes in two arguments, which are a callback function as the first argument that returns the PDF file object and an object as the second with the `config` prop. Please visit here to see PDF configuration options that can be passed into the `config` prop. ```jsx const callback = (pdf) => { console.log('pdf', pdf); }; createPDF(callback, { config: { margin: [2, 0], // default margin filename: `${document.title.split(' ').join('')}.pdf`, // default filename }, }); ``` ## Examples Refer to [PrintProvider](../ui/print-provider) for example usage of `usePrint` and the three functions provided. --- id: use-query category: State Management title: useQuery description: Hook for making GraphQL queries. pagination_prev: web/hooks/use-print pagination_next: web/hooks/use-router --- ## Usage The `useQuery` hook allows you to turn your GraphQL queries into custom hooks. This functions similarly to the popular GraphQL library Apollo. `useQuery` helps keep your API logic in line with React methodology and best practices. ## Getting started First, create your GQL query file. The example below queries for a person and is named **GetPerson.gql** ```jsx query Person($personId: ID!) { person(msid: $personId) { name email company location } } ``` Next, insert the following code in the **index.js** ```js export { usePersonSearch } from './usePersonSearch'; ``` Then create a custom hook for your query. This example is named **usePersonSearch.js** ```js import { useQuery } from '@uhg-abyss/web/hooks/useQuery'; import GetPerson from './GetPerson.gql'; export const usePersonSearch = (options) => { return useQuery(GetPerson, { ...options, url: '/api/graphql', accessor: 'person', initialState: { name: '', email: '', company: '', location: '', }, }); }; ``` Now, you can call the query from within your application. This example uses a submit button and search box to run the query search. This example component is named **QueryPage.jsx** ```jsx import React, { useState } from 'react'; import { Button } from '@uhg-abyss/web/ui/Button'; import { TextInput } from '@uhg-abyss/web/ui/TextInput'; import { usePersonSearch } from '@src/hooks/usePersonSearch'; export const QueryPage = () => { const [searchValue, setSearchValue] = useState(); const [personSearchResult, getPersonSearch] = usePersonSearch(); const { person } = personSearchResult.data; const handleSearch = () => { getPersonSearch({ variables: { personId: searchValue, }, }); }; const handleChange = (e) => { setSearchValue(e.target.value); }; return (

Name: {person?.name}
Email: {person?.email}
Company: {person?.company}
Location: {person?.location}

); }; ``` ## Query provider Wrap your code in the `QueryProvider` to access all calls made from components within the provider ```jsx import { QueryProvider } from '@uhg-abyss/web/ui/QueryProvider'; export const ReactComponentWithQueryProvider = ({ ...props }) => { return {/* all components you wish to wrap */}; }; ``` Access query data through `QueryContext`. The `queryState` property will contain your data categorized by GQL query name. ```jsx import React, { useContext } from 'react'; import { QueryContext } from '@uhg-abyss/web/hooks/useQuery'; export const ComponentToReadQueryProvider = ({ ...props }) => { const queryContext = useContext(QueryContext); return ( { queryContext?.queryState?.['nameOfYourQuery']?.data?.[ 'propertyYouWishToAccess' ] } ); }; ``` ## Option arguments Below is a list of available option arguments and their uses. ```jsx const options = { url: 'example/api/graphql', // URL endpoint requestPolicy: 'no-cache' // set to 'no-cache' to disable data cache headers:{ "Content-Type": 'application/json', "Authorization": "bearer_token_here" }, // header object initialState: {} // object that holds the initial state of data being queried onCalled: console.log('onCalled'), // function that runs when request is called onCompleted: console.log('onCompleted'), // function that runs when request is completed onError: console.log('onError'), // function that runs when request fails onCache: console.log('onCache'), // function that runs when data is cached clearCache: [''], // array of keys to clear from cache } ``` --- id: use-router category: State Management title: useRouter description: Hook for using browser information and navigation. pagination_prev: web/hooks/use-query pagination_next: web/hooks/use-collapse --- ## Usage The `useRouter` hook is based on the React Router Dom Library. This hook provides several methods that allow users to manage and interact with routing and navigation. `useRouter` should be used within the context of a [RouterProvider](/web/ui/router-provider). ```jsx import { useRouter } from '@uhg-abyss/web/hooks/useRouter'; ``` ## matchPath `matchPath` matches a path with a set of given parameters. The first argument is a path string. The second is a JSON object with a path variable and optional arguments. `matchPath` will return a JSON object if paths match or `null` if they do not. ```jsx const { matchPath } = useRouter(); const match = matchPath('/users/123', { path: '/users/:id', // either a single string or an array of strings exact: true, // optional, defaults to false strict: false, // optional, defaults to false }); // returns object if true and null if false // { // isExact: true // params: { // id: "2" // } // path: "/users/:id" // url: "/users/2" // } ``` ## navigate The `navigate` hook returns a function that lets you navigate programmatically. Below is an example of a button component that will navigate to the getting started page when clicked. ```jsx const NavigationButton = () => { const { navigate } = useRouter(); return ( ); }; ``` ## getLocation `getLocation` returns a JSON object with information about current router location. It is commonly used to trigger useEffect logic when location changes. It can return one of three values: - **React Router location object** — when inside a RouterProvider context. - **Native browser location object** — when outside Router context in a browser. - **null** — when no location is available (for example, in server-side rendering, certain test environments, or before the router has initialized). ```jsx const { getLocation } = useRouter(); let location = getLocation(); React.useEffect(() => { console.log(location); }, [location]); // location variable Value example // { // pathname: '/', // search: '', // hash: '', // state: null, // key: 'zflihx26' // } ``` **Note on TypeScript:** Due to TypeScript limitations in distinguishing between `RRLocation` and `Location`, the return type of `getLocation()` is `any`. You can manually cast the type before accessing type-specific properties like `state` or `href`. ```jsx import { useRouter } from '@uhg-abyss/web/hooks/useRouter'; import { Location as RRLocation, useInRouterContext } from '@uhg-abyss/web/tools/reactRouterTools/reactRouterDom'; //... const { getLocation } = useRouter(); let location = getLocation(); let inRouterContext = false; if (useInRouterContext) { inRouterContext = useInRouterContext(); } if (inRouterContext && location) { const rrLoc = location as RRLocation; console.log('React Router location state:', rrLoc.state); } else if (location) { const browserLoc = location as Location; console.log('Browser location href:', browserLoc.href); } else { console.log('No location available (Null)'); } ``` ## getRouteParams `getRouteParams` returns an object of key/value pairs of the dynamic params from the current URL. Pass a path variable to return params specific to that path. ```jsx const { getRouteParams } = useRouter(); const params = getRouteParams(); const paramsOnPath = getRouteParams('/pathExample'); ``` ## getSearchParams `getSearchParams` is used to read the query string in the URL for the current location and returns all search parameters. ```jsx const { getSearchParams } = useRouter(); const [searchParams] = getSearchParams(); ``` ## usePathComparison `usePathComparison` is not part of `useRouter`, but functions on similar logic. It can be used to compare a given URL with the current url. Returns `true` if both paths match or `false` if they do not ```jsx import { usePathComparison } from '../usePathComparison'; ``` ```jsx const urlIsSameAsCurrent = usePathComparison('url'); ``` ## Additional documentation Teams wanting to use React Router (v6) directly can import from these paths to ensure consistent versions across your application: ```tsx import { useLocation, useParams, } from '@uhg-abyss/web/tools/reactRouterTools/reactRouter'; ``` ```tsx import { Link, useNavigate, } from '@uhg-abyss/web/tools/reactRouterTools/reactRouterDom'; ``` --- id: use-scroll-trigger category: UI & DOM title: useScrollTrigger description: The useScrollTrigger is a custom hook for handling scroll behavior for any scrollable element. pagination_prev: web/hooks/use-media-query pagination_next: web/hooks/use-countdown --- ```jsx import { useScrollTrigger } from '@uhg-abyss/web/hooks/useScrollTrigger'; ``` ## Usage `useScrollTrigger` handles scroll behavior for any scrollable element. Basic usage works the same way as element.scrollIntoView(). Hook adjusts scrolling animation with respect to the `reduced-motion` user preference. ```jsx live () => { const { scrollIntoView, targetRef, scrollableRef } = useScrollTrigger({ offset: 60, }); return (

Hello there

); }; ``` ## Api Hook is configured with settings object: - `onScrollFinish` - function that will be called after scroll animation - `easing` - custom math easing function - `duration` - duration of scroll animation in milliseconds, default is `1250` - `axis` - axis of scroll, default is `y` - `cancelable` - indicator if animation may be interrupted by user scrolling. Default is `true` - `offset` - additional distance between nearest edge and element. Default is `0` - `isList` - indicator that prevents content jumping in scrolling lists with multiple targets, e.g. Select, Carousel. Default is `false` Hook returns an object with: - `scrollIntoView` - function that starts scroll animation - `scrollStop` - function that stops scroll animation - `targetRef` - ref of target HTML node - `scrollableRef` - ref of scrollable parent HTML element. If not used, document element will be used Returned `scrollIntoView` function accepts single optional argument `alignment` - optional target element alignment relatively to parent based on current axis. Default value of `alignment` is `start`. ```jsx scrollIntoView({ alignment: 'center' }); ``` ## Easing Hook accept custom `easing` math function to control the flow of animation. It takes `t` argument, which is a number between `0` and `1`. Default easing is `easeInOutQuad` - more info here . You can find other popular examples on easings.net. ```jsx default value of easeInOutQuad useScrollTrigger({ easing: (t) => (t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t) }); ``` ## Parent node ```jsx live () => { const { scrollIntoView, targetRef, scrollableRef } = useScrollTrigger(); return (

Scroll me into view

); }; ``` ## Scroll X axis ```jsx live () => { const { scrollIntoView, targetRef, scrollableRef } = useScrollTrigger({ axis: 'x', }); return (

Scroll me into view

); }; ``` ## Drawer ```jsx live () => { const [isOpen, setIsOpen] = useState(false); const { scrollIntoView, targetRef, scrollableRef } = useScrollTrigger({ offset: 60, }); return ( setIsOpen(false)} ref={scrollableRef} >

Scroll me into view

); }; ``` ## Modal ```jsx live () => { const { scrollIntoView, targetRef, scrollableRef } = useScrollTrigger(); const [isOpen, setIsOpen] = useState(false); return ( setIsOpen(false)} ref={scrollableRef} >

Scroll me into view

); }; ``` ## Properties ```typescript useScrollTrigger({ onScrollFinish?: () => {}; duration?: number; axis?: 'x' | 'y'; easing?: (t: number) => number; offset?: number; cancelable?: boolean; isList?: boolean; sRef?: MutableRefObject tRef?: MutableRefObject }): { targetRef: MutableRefObject; scrollableRef: MutableRefObject; scrollIntoView: ({ alignment?: 'start' | 'end' | 'center'; }) => {}; scrollStop: () => {}; }; ``` --- id: use-token category: Utilities title: useToken description: Used to get values mapped to tokens. --- ```jsx import { useToken } from '@uhg-abyss/web/hooks/useToken'; ``` This hook returns a function that is used to get the style value associated with a token defined in the theme. Use this whenever you want to pass in a prop with the value of a token string instead of the associated token value. ## Properties ```typescript type TokenKey = 'colors' | 'space' | 'sizes' | 'fontSizes' | 'lineHeights' | 'fontWeights' | 'fonts' | 'radii' | 'borderWidths' | 'shadows' | 'letterSpacings' | 'borderStyles' | 'opacities'; interface TokenConfig { retain?: boolean; }; useToken(key: TokenKey, config?: TokenConfig) ``` ## Usage The `key` argument corresponds to the upper level category inside the theme. Start with defining a function and passing it the string of the token key. You can then use that function to pass in your token element and get the associated value. A hex value can also be passed in as a `token` and it will be returned as-is, unless set not to using the `retain` configuration option. ```jsx const theme = { theme: { colors: {...}, space: {...}, fontSizes: {...}, fonts: {...}, }, }; const getColorToken = useToken('colors'); const color = getColorToken('$primary1'); ``` ## Example ```jsx live () => { const getColorToken = useToken('colors'); const color = getColorToken('$interactive3'); const getSpaceToken = useToken('space'); const space = getSpaceToken('$md'); return ( Abyss Design System ); }; ``` ### Defaults By default, the `useToken` hook uses the passed in value if the token is not found/is invalid. This allows it to take hex and string values and return them as given. Using the `config` parameter, you can pass in `{retain: false}` to require tokenized values. ```jsx live () => { const getSpaceToken = useToken('space'); const space = getSpaceToken('$md'); const getColorToken = useToken('colors'); const color = getColorToken('#D9E9FA'); const color2 = getColorToken('gray'); const getColorToken2 = useToken('colors', { retain: false }); const color3 = getColorToken2('#D9E9FA'); return (

Abyss Design System

); }; ``` --- id: use-translate category: Utilities title: useTranslate description: Used to retrieve translated strings from the Abyss i18n object and supply values to the placeholders. sourceIsTS: true --- ```jsx import { useTranslate } from '@uhg-abyss/web/hooks/useTranslate'; ``` ## Usage ```ts interface I18nTranslate { t: (key: string, replacements?: object) => string; i18n: object; } useTranslate(key: string, replacements?: object): I18nTranslate ``` The `key` argument corresponds to the key in the `i18n` object. The `replacements` argument is an object that contains the value(s) to replace in the translated string. ## Example Let's use an example to illustrate how the `useTranslate` hook works. The [ResultCount](/web/ui/pagination#resultcount) component displays the currently visible results and the total number of results. We can get the value of this text with the key `'ResultCount.multipleResults'`. ```jsx live-expanded () => { const { t } = useTranslate(); return {t('ResultCount.multipleResults')}; }; ``` Notice the values in double curly braces (`{{ }}`). These are placeholder values. If we want to manually replace these, we can pass in the `replacements` object with the keys `resultFrom`, `resultTo`, and `resultsTotalCount`. ```jsx live-expanded () => { const { t } = useTranslate(); return ( {t('ResultCount.multipleResults', { resultFrom: 1, resultTo: 5, resultsTotalCount: 10, })} ); }; ``` **Note:** In regular usage of Abyss components, passing these replacements in manually is unnecessary. All components will automatically replace these placeholders with the correct values. We can also use the `useTranslate` hook to get the translated string from the `i18n` object. Note that this method does not provide a built-in way to supply values to the placeholders. ```jsx live-expanded () => { const { i18n } = useTranslate(); return {i18n.ResultCount.multipleResults}; }; ``` ## Related links - [I18nProvider](/web/ui/i18n-provider) - [Translate](/web/ui/translate) --- id: use-visually-hidden category: Accessibility title: useVisuallyHidden description: The useVisuallyHidden is a custom hook for visually hiding content. pagination_prev: null --- ```jsx import { useVisuallyHidden } from '@uhg-abyss/web/hooks/useVisuallyHidden'; ``` ## Usage ```jsx export const useVisuallyHidden = () => { const visuallyHiddenProps = { style: { border: 0, clip: 'rect(0 0 0 0)', clipPath: 'inset(50%)', height: 1, margin: '0 -1px -1px 0', overflow: 'hidden', padding: 0, position: 'absolute', width: 1, whiteSpace: 'nowrap', }, }; return { visuallyHiddenProps }; }; ``` --- id: about slug: /web/about title: About Abyss --- ## What is Abyss? ## How Abyss works ## We support adoption ## Guiding principles ## We maintain assets ## The Abyss team --- id: contact-us slug: /web/contact-us title: Contact Us hide_table_of_contents: true --- ## Support ## Requests --- id: overview slug: /web/overview title: Overview hide_table_of_contents: true --- ## --- id: product-roadmap slug: /web/product-roadmap title: Product Roadmap --- For 2024, please see details below that outline the Goals/Themes, Solutions Capabilities, and PI Plans for the Abyss Design System. Please note, this page will be updated at the beginning of each PI. ## Abyss business objectives for 2024 ## Solution capabilities To achieve greater adoption and consistency, below are the overarching Solution Capabilities for Abyss that outline some more specific initiatives the team is working toward. For additional details, check out our Aha Board on Solution Capabilities. ## Abyss Web Development ### PI plan - Further breaking down our Solution Capabilities, below is our outline for current, upcoming PI Plans and the key features being addressed in each of the 5 sprints. - For additional details on items that will fall under each of these Solution Capabilities, check out our Aha Feature board ** Note: items below are subject to change as priorities shift throughout each sprint. ** ## Abyss Web Design ### PI plan - Further breaking down our Solution Capabilities, below is our outline for current, upcoming PI Plans and the key features being addressed in each of the 5 sprints. ** Note: items below are subject to change as priorities shift throughout each sprint. ** --- id: releases slug: /web/releases title: Releases --- --- id: accessibility title: Accessibility --- ## Overview ## Interactive components ```jsx sandbox { component: 'Button', inputs: [ { prop: 'variant', type: 'select', options: [ { label: 'solid', value: 'solid' }, { label: 'outline', value: 'outline' }, { label: 'ghost', value: 'ghost' }, ], }, { prop: 'size', type: 'string', }, { prop: 'children', type: 'string', }, { prop: 'isDisabled', type: 'boolean' }, ], } ```
```jsx render ``` ## Color contrast ```jsx render ``` ## Visually hidden content Visually hidden content refers to content that is visually hidden, but remains accessible to assistive technology. This content can be styled using the [useVisuallyHidden hook](/web/hooks/use-visually-hidden/) from the Abyss library. This can be useful in situations where additional visual information or cues need to be conveyed to non-visual users, or in interactive control situations where the component is focusable. ## Icons ### Meaningful or control icons If the icon is being used in a setting where it is the only element providing meaning, then that same meaning should be conveyed to screen reader users. The below implementation provides examples of situations in which the property `isScreenReadable` should be set to true and the `title` property is required and should describe the purpose of the image. Example 1: An alert icon is used to convey a sense of urgency; there is adjacent text (“There is a data outage”) but the text doesn't include any words that convey urgency. So, in this case, the icon should have a text alternative such as “Alert” or “Warning”. ```jsx live

There is a data outage

```
Example 2: An “X” material icon is used as a close button on a modal dialog. There is no adjacent text, so the icon should have a text alternative of “close” or “close window”. ```jsx live ``` ### Decorative icons If the icon is being used in a setting in which it is just a decorative element (which is the default case for icons), then the icon should be ignored by screen readers. The below implementation provides example of which situations would be classified as decorative. Since the default of `isScreenReadable` is set to false no specific changes need to be made for decorative icons. Example 1: An alert icon is used next to an urgent message and the word “Alert” is included in the adjacent text. In this case, the icon becomes decorative in nature and should be ignored by screen readers. ```jsx live

Alert: There is a data outage

``` ## Additional resources --- id: product-inclusion title: Product Inclusion --- ## Mission statement ## Product inclusion principles ## Product inclusion checklist ## Product inclusion audit tool ## Contact us --- id: product-resources title: Product Resources --- ## Overview ## How does Abyss work? ## Versioning ## Branding ## Accessibility ## Support --- id: adobe-analytics title: adobe analytics category: Util --- ```jsx render ``` ## Register events The first step for setting up `Adobe Analytics` in the project is by registering the Adobe event listener on initial load. Below is the code snippet for registering Adobe event listener. `registerEvents` function will be called in the root of the project folder. ```jsx import { event } from '@uhg-abyss/web/tools/event'; import { adobeAnalytics } from '@uhg-abyss/web/tools/event/listeners/adobeAnalytics'; const adobeTags = { PRINT_START: () => { return { event: 'print', data: {}, }; }, }; export const registerEvents = (metaData) => { let isLocalhost = false; if (typeof window !== 'undefined') { isLocalhost = window.location.hostname === 'localhost'; window.onbeforeprint = () => { return event('PRINT_START'); }; } event.listener( adobeAnalytics({ id: 'adobe-analytics-abyss', enabled: true, logging: true, events: adobeTags, metadata: metaData, }) ); }; ``` ## Data layer key If your launch script uses a different data layer then `appEventDataLayer` you can use the prop `dataLayerKey` to override it. Please consult with the Adobe team if you are unsure of what data layer is used in your launch script. Most teams will be using `appEventDataLayer` so there will be no need to use this prop. ```jsx adobeAnalytics({ dataLayerKey: 'string', // only use if your data layer key is different from the default (appEventDataLayer) }); ``` ## Adobe tags `Adobe Tags` is the object of event functions, where each event returns the type of event and data need to be displayed. `Adobe tags` were passed as `events` to the `adobeAnalytics` listener as shown in above code snippet. Below is the code snippet example for `PRINT_START` event function. ```jsx export const adobeTags = { PRINT_START: () => { return { event: 'print', data: {}, }; }, }; ``` --- id: config category: Util title: config description: Tool to access environment variables. --- ```jsx import { config } from '@uhg-abyss/web/tools/config'; ``` ## Dev env config example ** Note: [Abyss App Starter-Kit](/web/developers/abyss-app/installation/) Only ** In the example below we are running the config tool in the `dev` environment. Running `config` without passing it a value will return the available config including the global variables and environment specific variables. The `config` method also can accept a variable name and returns it's value. ### Environment variables Below is a standard setup for the environment config. Read more about Abyss environment configurations [here](/web/developers/abyss-app/environments). ```json { "env": { // Global variables "APP_NAME": "Create Abyss App - Micro Frontend" }, "env.dev": { // Env specific variables "ENV_VAR": "dev-only" }, "env.test": { "ENV_VAR": "test-only" }, "env.stage": { "ENV_VAR": "stage-only" }, "env.prod": { "ENV_VAR": "prod-only" } } ``` ### Config Example config uses: ```jsx const allConfigVariables = config(); // { // APP_NAME: 'Create Abyss App - Micro Frontend', // ENV_VAR: 'dev-only', // } const appName = config('APP_NAME'); // "Create Abyss App - Micro Frontend" const appEnv = config('ENV_VAR'); // "dev-only" ``` --- id: create-script category: Util title: createScript description: Tool for create and add scripts --- ```jsx import { createScript } from '@uhg-abyss/web/tools/script'; ``` ## Overview The `createScript` tool simplifies creating and adding scripts to the document head. It takes in an id, src, and callback. ## Usage Example of setting a script link to a variable, and passing it into createScript. The script will then get added to the document head. ```jsx const scriptLink = 'https://examplescriptlink.com/script'; const callback = () => { // Do something }; createScript('unique-id', scriptLink, callback); ``` ## Properties ```jsx createScript( id: string, src: string || function, callback: callback function ) ``` --- id: create-store category: Util title: createStore description: Tool for state-management --- ```jsx import { createStore } from '@uhg-abyss/web/tools/createStore'; ``` ```jsx render Moving forward, please install{' '} zustand within your application. ``` ## Overview The `createStore` tool leverages zustand, a lightweight React state-management alternative to Redux and Context and deals with common pitfalls such as the zombie child problem, react concurrency and context loss between mixed renderers. **Why zustand over redux** - Simple and un-opinionated - Makes hooks the primary means of consuming state - Doesn't wrap your app in context providers - Can inform components without causing render **Why zustand over context** - Less Boilerplate - Renders components only on changes - Centralized, action-based state management ## Usage The `createStore` tool integrates the zustand library into Abyss and allows for its usage without additional installation. Simply import `createStore` into your application, and you have access to the full list of features that zustand has to offer. See the usage example below on how to create a basic store and utilize it throughout your application to persist data between pages. For further details and implementation of this tool, please see the proceeding sections below. ```jsx import { createStore } from '@uhg-abyss/web/tools/createStore'; export const useStore = createStore((set) => { return { formOne: null, formTwo: null, setForms: (formValues) => { return set(() => { return { ...formValues }; }); }, }; }); ``` Fill out the forms below and use the buttons to navigate between the page components to see how the state of the form on each page persists between changes. ```jsx live () => { const [showPageOne, setShowPageOne] = useState(true); const PageOneForm = React.memo(() => { const emptyDefaultValues = { firstName: '', lastName: '', }; const { formOne: currentStoreValues, setForms } = utils.useStore(); const form = useForm({ defaultValues: currentStoreValues || emptyDefaultValues, }); useEffect(() => { return () => { const currentFormValues = form.getValues(); setForms({ formOne: currentFormValues }); }; }, []); return ( Page One Form ); }); const PageTwoForm = React.memo(() => { const emptyDefaultValues = { acceptTerms: false, selectList: '', }; const { formTwo: currentStoreValues, setForms } = utils.useStore(); const form = useForm({ defaultValues: currentStoreValues || emptyDefaultValues, }); useEffect(() => { return () => { const currentFormValues = form.getValues(); setForms({ formTwo: currentFormValues }); }; }, []); return ( Page Two Form e.preventDefault()} /> ); }); return showPageOne ? : ; }; ``` ## Create store To start, you can create a store. The store is the hook, where you can put anything essentially in it: primitives, objects, and functions. State has to be updated immutably, and to assist with this, the `set` function merges state. ```jsx const useStore = createStore((set) => ({ count: 1, inc: () => set((state) => ({ count: state.count + 1 })), })); ``` ## Binding components You can use the hook anywhere without providers. To select a specific state, pass in a string selector with the name of the state property as the first argument in the hook. The component will re-render on changes. ```jsx const Controls = () => { const inc = useStore('inc'); return ; }; const Counter = () => { const count = useStore('count'); return

Count: {count}

; }; ``` ```jsx live () => { const useStore = createStore((set) => ({ count: 1, inc: () => set((state) => ({ count: state.count + 1 })), })); const Controls = () => { const inc = useStore('inc'); return ; }; const Counter = () => { const count = useStore('count'); return Count: {count}; }; return ( ); }; ``` ## Fetching everything Zustand does have the ability to fetch everything, but please note that it will cause the component to update on every state change. ```jsx const state = useStore(); ``` ## Multiple state slices By default, zustand detects changes with strict equality when comparing (old === new). ```jsx const count = useStore('count'); const countTwo = useStore('countTwo'); ``` If you'd like to construct a single object with multiple state-picks inside, similar to redux's mapStateToProps, you can tell zustand that you'd like the object to be diffed shallowly. This will automatically be implemented whenever a [Custom Equality Function](#custom-equality-function) is NOT passed in as a second argument to the store hook. If a new Array or Object is returned, this will always be considered a change even if the content is the same. Thus, if returning an Object or Array, use the shallow comparison. --> ```jsx //Object pick, uses shallow comparison and re-renders component when count or countTwo change const { count, countTwo } = useStore((state) => { count: state.count, countTwo: state.countTwo }); // Array pick, uses shallow comparison and re-renders the component when either count or countTwo change const [count, countTwo] = useStore((state) => [ state.count, state.countTwo ]); // Mapped picks, uses shallow comparison and re-renders the component when state.allCounts changes in order, count or keys const allCounts = useStore((state) => Object.keys(state.allCounts)); ``` ### Custom equality function You can provide a custom equality function for more control over re-rendering. ```jsx const allCounts = useStore( (state) => state.allCounts, (newCount, oldCount) => compare(newCount, oldCount) ); ``` ## Overwriting state The `set` function has a second argument that is by default set to `false`. Instead of merging, it replaces the state model. Be careful not to delete parts like actions that you rely on. ```jsx import omit from 'lodash-es/omit'; const useStore = create((set) => ({ count: 1, countTwo: 2, deleteEverything: () => set({}, true), // clears the entire store, actions included deleteCountTwo: () => set((state) => omit(state, ['countTwo']), true), // removes countTwo from state model })); ``` ## Async actions It does not matter to zustand if your actions are async or not; you just have to call `set` when ready. ```jsx const useStore = createStore((set) => ({ totalCount: 0, fetch: async (totalCount) => { const response = await fetch(totalCount); set({ totalCount: await response }); }, })); ``` ## Read from state in actions `set` allows fn-updates `set(state => result)`. However, you can still access the state outside of it through `get`. ```jsx const useStore = createStore((set, get) => ({ count: 100, action: () => { const count = get().count; // ... }, })); ``` ## Reading/writing state and reacting to changes outside components Sometimes you need to access state in a non-reactive way, or act upon the store. For these cases the resulting hook has utility functions attached to its prototype. ```jsx const useTeamStore = createStore(() => ({ tshirts: true, jerseys: true, shoes: true, })); // Getting non-reactive fresh state const tshirts = useTeamStore.getState().tshirts; // Listening to all changes, fires synchronously on every change const unsub1 = useTeamStore.subscribe(console.log); // Updating state, will trigger listeners useTeamStore.setState({ tshirts: false }); // Unsubscribe listeners unsub1(); ``` ## Transient updates (for often occurring state-changes) The subscribe function allows components to bind to a state-portion without forcing re-render on changes. Combine it with useEffect for automatic unsubscribe on unmount. This can make a drastic performance impact when you are allowed to mutate the view directly. ```jsx const useStore = createStore((set) => ({ count: 0, ... })) const Component = () => { // Fetch initial state const countRef = useRef(useStore.getState().count) // Connect to the store on mount, disconnect on unmount, catch state-changes in a reference useEffect(() => useStore.subscribe( state => (countRef.current = state.count) ), []) } ``` --- id: create-theme-optum category: Styling title: createTheme description: Tool to create and modify Optum themes customProps: { brand: optum } sourcePath: tools/theme/createTheme/createTheme.js --- **Note:** This page is specific to the `optum` theme. For other themes, please switch to the appropriate theme in the top right corner of the page. ```jsx import { createTheme } from '@uhg-abyss/web/tools/theme'; ``` The tool `createTheme` allows for the creation of preset themes and allows you to override those themes to fit your design needs. `createTheme` is used in conjunction with [ThemeProvider](/web/ui/theme-provider). ## Properties ```typescript createTheme( theme: string, override?: object, ): object; ``` ## Usage `createTheme` takes in two arguments. The first argument is the choice of a default theme. There are currently 4 themes available `'optum | 'uhc' | 'uhg' | 'abyss'`. If no theme is chosen, it will fall back to the default `'abyss'` theme. The second argument is any [overrides](#theme-overrides) you wish to apply to the base theme you've chosen. Abyss theming leverages Stitches, to see more about theme configuration, head [here](https://stitches.dev/docs/tokens). See the next section on how to apply theme overrides. ## Theme overrides As mentioned previously there is an optional second argument that can be passed into the `createTheme` function to override the default [theme tokens](#abyss-theme-tokens) and/or create your own custom tokens that can be utlized using our [styled](/web/tools/styled) tool or the available [css](/web/developers/theming-styling/#css-prop) prop on each component. This is useful when you want to customize the theme for a specific project or brand. ```jsx import { ThemeProvider } from '@uhg-abyss/web/ui/ThemeProvider'; import { createTheme } from '@uhg-abyss/web/tools/theme'; const themeOverride = { theme: { colors: { // primary primary1: '#002677', primary2: '#FFFFFF', // interactive interactive1: '#196ECF', interactive2: '#0C55B8', }, space: {...}, fontSizes: {...}, fonts: {...}, fontWeights: {...}, lineHeights: {...}, letterSpacings: {...}, sizes: {...}, borderWidths: {...}, borderStyles: {...}, radii: {...}, shadows: {...}, zIndices: {...}, transitions: {...}, }, css: { // provide custom css h1: { fontSize: '32px', fontWeight: '700', }, }, deprecatedFont: boolean, // added in v1.52.0 - see below for details deprecatedOptumIcons: boolean, // add in v1.54.0 - see below for details }; const theme = createTheme('optum', themeOverride); const App = () => { return ...; }; ReactDOM.render(, document.getElementById('root')); ``` ## Abyss theme tokens You can create your own themes and override the default tokens by following one of the two current paths: - **V1 Components** - override the [Legacy tokens](#legacy-tokens) referenced below, which are utlized within V1 instances of our components. _**Note**: these legacy tokens will be replaced with official Figma designed, component, semantic and core level tokens in future major releases._ - **V2 Components** - utilize the [flattenTokens](/web/tools/flatten-tokens) tool to apply custom theme overrides to our currently available, core and semantic level tokens for all V2 components. ### Legacy tokens ## Important: font deprecation The built-in fonts for each brand theme have changed as of [Abyss v1.52.0](https://github.com/uhc-tech/abyss/releases/tag/v1.52.0). The Optum Sans font is being decommissioned in favor of the new Enterprise Sans font. For more information on the new font, please see the following Brand documentation. The existing legacy, Optum Sans, font will remain available for the time being and can be enabled by setting the `deprecatedFont` property to `true` in the `themeOverride` object: ```jsx const themeOverride = { deprecatedFont: true, }; const theme = createTheme('optum', themeOverride); ``` Note: Any customization to the `fonts` field in the `theme` object will still override the `deprecatedFont` setting. ## Important: Optum icons deprecation The Optum icons used in `IconBrand` have been updated in [Abyss v1.54.0](https://github.com/uhc-tech/abyss/releases/tag/v1.54.0). The new icons correspond to the icons available on the Optum Brand website. The old icons will remain available for the time being and can be enabled by setting the `deprecatedOptumIcons` property to `true` in the `themeOverride` object. ```jsx const themeOverride = { deprecatedOptumIcons: true, }; ``` --- id: create-theme-uhc category: Styling title: createTheme description: Tool to create and modify UHC themes customProps: { brand: uhc } sourcePath: tools/theme/createTheme/createTheme.js --- **Note:** This page is specific to the `uhc` theme. For other themes, please switch to the appropriate theme in the top right corner of the page. ```jsx import { createTheme } from '@uhg-abyss/web/tools/theme'; ``` The tool `createTheme` allows for the creation of preset themes and allows you to override those themes to fit your design needs. `createTheme` is used in conjunction with [ThemeProvider](/web/ui/theme-provider). ## Properties ```typescript createTheme( theme: string, override?: object, ): object; ``` ## Usage `createTheme` takes in two arguments. The first argument is the choice of a default theme. There are currently 4 themes available `'uhc | 'optum' | 'uhg' | 'abyss'`. If no theme is chosen, it will fall back to the default `'abyss'` theme. The second argument is any [overrides](#theme-overrides) you wish to apply to the base theme you've chosen. Abyss theming leverages Stitches, to see more about theme configuration, head [here](https://stitches.dev/docs/tokens). See the next section on how to apply theme overrides. ## Theme overrides As mentioned previously there is an optional second argument that can be passed into the `createTheme` function to override the default [theme tokens](#abyss-theme-tokens) and/or create your own custom tokens that can be utlized using our [styled](/web/tools/styled) tool or the available [css](/web/developers/theming-styling/#css-prop) prop on each component. This is useful when you want to customize the theme for a specific project or brand. ```jsx import { ThemeProvider } from '@uhg-abyss/web/ui/ThemeProvider'; import { createTheme } from '@uhg-abyss/web/tools/theme'; const themeOverride = { theme: { colors: { // primary primary1: '#002677', primary2: '#FFFFFF', // interactive interactive1: '#196ECF', interactive2: '#0C55B8', }, space: {...}, fontSizes: {...}, fonts: {...}, fontWeights: {...}, lineHeights: {...}, letterSpacings: {...}, sizes: {...}, borderWidths: {...}, borderStyles: {...}, radii: {...}, shadows: {...}, zIndices: {...}, transitions: {...}, }, css: { // provide custom css h1: { fontSize: '32px', fontWeight: '700', }, }, enterpriseFont: boolean, // added in v1.59.0 - see below for details deprecatedFont: boolean, // deprecated in v1.59.0+ - see below for details }; const theme = createTheme('uhc', themeOverride); const App = () => { return ...; }; ReactDOM.render(, document.getElementById('root')); ``` ## Abyss theme tokens You can create your own themes and override the default tokens by following one of the two current paths: - **V1 Components** - override the [Legacy tokens](#legacy-tokens) referenced below, which are utlized within V1 instances of our components. _**Note**: these legacy tokens will be replaced with official Figma designed, component, semantic and core level tokens in future major releases._ - **V2 Components** - utilize the [flattenTokens](/web/tools/flatten-tokens) tool to apply custom theme overrides to our currently available, core and semantic level tokens for all V2 components. ### Legacy tokens ## IMPORTANT: font updates - [Abyss versions [v1.59.0] and above](#abyss-versions-v1590-and-above) - [Abyss versions [v1.52.0] to [v1.58.0]](#abyss-versions-v1520-to-v1580) ### Abyss versions [v1.59.0] and above Following brand's directive, Abyss is reverting the default font back to **UHC Sans**. For teams, this means the **Enterprise Sans** font will no longer be the default font for the `uhc` theme. The `deprecatedFont` flag will no longer be available. Instead, teams looking to utilize **Enterprise Sans** can do so by setting the `enterpriseFont` property to `true` in the `themeOverride` object. For example, to use the Enterprise Sans font, you could create the theme like this: ```jsx const themeOverride = { enterpriseFont: true, // only use this flag for UHC theme }; const theme = createTheme('uhc', themeOverride); ``` ### Abyss versions [v1.52.0] to [v1.58.0] The built-in default font for UHC was changed to **Enterprise Sans** in version [Abyss v1.52.0](https://github.com/uhc-tech/abyss/releases/tag/v1.52.0) and remains so through version 1.58.0. We recommend upgrading to the latest version of Abyss, but if you decide to remain on versions `1.52.0` - `1.58.0` and want to utilize **UHC Sans** you must set the `deprecatedFont` property to `true` in the `themeOverride` object: ```jsx const themeOverride = { deprecatedFont: true, }; const theme = createTheme('uhc', themeOverride); Note: Any customization to the `fonts` field in the `theme` object will still override the `deprecatedFont` setting. ``` **Note:** As detailed in the [previous section](#abyss-versions-v1590-and-above) the `deprecatedFont` flag is longer available for the `uhc` theme in Abyss versions [v1.59.0] and later. For more information on fonts and other brand related information, please see the following Brand documentation. --- id: create-theme-uhg category: Styling title: createTheme description: Tool to create and modify UHG themes customProps: { brand: uhg } sourcePath: tools/theme/createTheme/createTheme.js --- **Note:** This page is specific to the `uhg` theme. For other themes, please switch to the appropriate theme in the top right corner of the page. ```jsx import { createTheme } from '@uhg-abyss/web/tools/theme'; ``` The tool `createTheme` allows for the creation of preset themes and allows you to override those themes to fit your design needs. `createTheme` is used in conjunction with [ThemeProvider](/web/ui/theme-provider). ## Properties ```typescript createTheme( theme: string, override?: object, ): object; ``` ## Usage `createTheme` takes in two arguments. The first argument is the choice of a default theme. There are currently 4 themes available `'uhg | 'uhc' | 'optum' | 'abyss'`. If no theme is chosen, it will fall back to the default `'abyss'` theme. The second argument is any [overrides](#theme-overrides) you wish to apply to the base theme you've chosen. Abyss theming leverages Stitches, to see more about theme configuration, head [here](https://stitches.dev/docs/tokens). See the next section on how to apply theme overrides. ## Theme overrides As mentioned previously there is an optional second argument that can be passed into the `createTheme` function to override the default [theme tokens](#abyss-theme-tokens) and/or create your own custom tokens that can be utlized using our [styled](/web/tools/styled) tool or the available [css](/web/developers/theming-styling/#css-prop) prop on each component. This is useful when you want to customize the theme for a specific project or brand. ```jsx import { ThemeProvider } from '@uhg-abyss/web/ui/ThemeProvider'; import { createTheme } from '@uhg-abyss/web/tools/theme'; const themeOverride = { theme: { colors: { // primary primary1: '#002677', primary2: '#FFFFFF', // interactive interactive1: '#196ECF', interactive2: '#0C55B8', }, space: {...}, fontSizes: {...}, fonts: {...}, fontWeights: {...}, lineHeights: {...}, letterSpacings: {...}, sizes: {...}, borderWidths: {...}, borderStyles: {...}, radii: {...}, shadows: {...}, zIndices: {...}, transitions: {...}, }, css: { // provide custom css h1: { fontSize: '32px', fontWeight: '700', }, }, deprecatedFont: boolean, // added in v1.52.0 - see below for details }; const theme = createTheme('uhg', themeOverride); const App = () => { return ...; }; ReactDOM.render(, document.getElementById('root')); ``` ## Abyss theme tokens You can create your own themes by overriding the [Legacy tokens](#legacy-tokens) referenced below. _**Note**: These legacy tokens will be replaced with official Figma designed, component, semantic and core level tokens in future major releases._ ### Legacy tokens ## Important: font deprecation The built-in fonts for each brand theme have changed as of [Abyss v1.52.0](https://github.com/uhc-tech/abyss/releases/tag/v1.52.0). The Graphik font is being decommissioned in favor of the new Enterprise Sans font. For more information on the new font, please see the following Brand documentation. The existing legacy, Graphik, font will remain available for the time being and can be enabled by setting the `deprecatedFont` property to `true` in the `themeOverride` object: ```jsx const themeOverride = { deprecatedFont: true, }; const theme = createTheme('uhg', themeOverride); ``` Note: Any customization to the `fonts` field in the `theme` object will still override the `deprecatedFont` setting. --- id: dayjs category: Util title: dayjs description: Library for parsing, validation, and manipulation of Date objects. --- ## Usage Abyss tools include the Day.js library, which can be used in your own components. Day.js is a minimalist JavaScript library that parses, validates, manipulates, and displays dates and times for modern browsers with a largely Moment.js-compatible API. ### Import Day.js ```jsx import { dayjs } from '@uhg-abyss/web/tools/dayjs'; ``` ### Usage examples Below are some common examples of how to use Day.js: ```jsx const currentDate = dayjs(); const dateFromIsoString = dayjs('2018-04-04T16:00:00.000Z'); const dateFromUnix = dayjs(1318781876406); const dateFromString = dayjs('07/01/2025', 'MM/DD/YYYY'); const dateInCurrentMonth = dayjs().date(); const sevenDaysFromCurrentDate = dayjs().add(7, 'day'); const millisecondsBetweenTwoDates = dayjs('2019-01-25').diff( dayjs('2018-06-05') ); ``` ## Installation recommendation While Abyss provides Day.js and several common plugins out of the box, we recommend installing Day.js separately in your project if you: - Need plugins that aren't included in Abyss - Want to control your own Day.js version - Have specific date/time manipulation requirements If you only need the basic plugins we provide, you can continue using the Abyss-provided version. ## Abyss default plugins The following [Day.js plugins](https://day.js.org/docs/en/plugin/plugin) are available in Abyss: - `isSameOrBefore` - `isSameOrAfter` - `isYesterday` - `isLeapYear` - `isTomorrow` - `isBetween` - `duration` - `toObject` - `isToday` - `customParseFormat` Example usage: ```jsx // Check if a date is between two other dates dayjs('2019-01-25').isBetween('2019-01-01', '2019-02-01'); // Convert to object dayjs('2019-01-25').toObject(); // Check if it's today dayjs().isToday(); // duration dayjs.duration(100); // isBetween dayjs('2010-10-20').isBetween('2010-10-19', dayjs('2010-10-25'), 'year'); // isTomorrow dayjs().add(1, 'day').isTomorrow(); // isLeapYear dayjs('2000-01-01').isLeapYear(); // isYesterday dayjs().add(-1, 'day').isYesterday(); // isSameOrAfter dayjs('2010-10-20').isSameOrAfter('2010-10-19', 'year'); // isSameOrBefore dayjs('2010-10-20').isSameOrBefore('2010-10-19', 'year'); ``` --- id: event category: Util title: event description: Tool for storing, retrieving and triggering events based on the event type. --- ```jsx import { event } from '@uhg-abyss/web/tools/event'; ``` ## Overview The `event` tool provides various functions for storing, retrieving, adding listeners to the window storage and also triggers custom events to track the analytics of the application. ## Triggering event The `event` function provided by the tool accepts `eventId` and `data` as parameters and performs the required action based on the event id passed which are defined in the events of listeners and gives the update data. ```jsx event('HOME_PAGE_LOAD', { message: 'page loaded successfully' }); ``` ## Get data The event tool provides `getData` function to get the data from window storage. ```jsx event.getData(); ``` ## Set data The event tool provides `setData` function to set the data in window storage. ```jsx event.setData({ message: 'set data' }); ``` ## Add listener The event tool provides `listener` function which accepts event listener as a parameter which will be added to window storage. Abyss provides three different event listeners `adobeAnalytics`, `newRelicAnalytics`, `qualtrics` Below is the code snippet of Adding Adobe listener to window storage. ```jsx import { adobeAnalytics } from '@uhg-abyss/web/tools/event/listeners/adobeAnalytics'; event.listener( adobeAnalytics({ id: 'adobe-analytics-abyss', enabled: true, logging: true, events: {}, metadata: {}, }) ); ``` --- id: flatten-tokens category: Styling title: flattenTokens description: Tool to combine tokens from multiple sources into a single object. customProps: { brand: [optum, uhc] } sourcePath: tools/theme/flattenTokens/flattenTokens.ts --- ```jsx import { flattenTokens } from '@uhg-abyss/web/tools/theme'; ``` ## Properties ```typescript flattenTokens(...themes: TokenTheme[]) ``` ## Usage _**NOTE:** This tool is only compatible with V2 versions of web components, which are officially designed with core and semantic tokens._ The `flattenTokens` function is designed to flatten and merge tokens from multiple JSON structures, to support a layered system where tokens from different themes can override core and semantic level tokens. The Abyss theme accepts an object with the following style category keys to define the theme: `sizing`, `spacing`, `color`, `borderRadius`, `borderWidth`, `boxShadow`, `fontFamilies`, `fontWeights`, `fontSizes`, `lineHeights`, `letterSpacing`, `border`, and `opacity`. This function will return a single object in this format that can be used to create a theme object via createTheme for later use in the [ThemeProvider](/web/ui/theme-provider). ## Overriding Abyss token theme In this example, we use `flattenTokens` and `createTheme` to create a new theme object, which is then passed into `ThemeProvider` to override the Abyss theme and customize the [V2Button](/web/ui/button-v2) and [V2Accordion](/web/ui/accordion-v2) components. ```jsx live const extractDescriptions = (coreTheme, semanticTheme) => { const descriptions = []; const extractFromTheme = (theme, path = '') => { Object.entries(theme).forEach(([key, item]) => { const currentPath = path ? `${path}.${key}` : key; if (item.description) { let updatedDescription = item.description.replace( 'core token', `$${currentPath}` ); updatedDescription = updatedDescription.replace( 'semantic token', `$${currentPath}` ); descriptions.push(updatedDescription); } if (typeof item === 'object' && !Array.isArray(item)) { extractFromTheme(item, currentPath); } }); }; extractFromTheme(coreTheme); extractFromTheme(semanticTheme); return descriptions; }; const coreTheme = { core: { color: { brand: { 100: { value: '#0071e3', type: 'color', description: 'Overrides core token used to define, primary Button background color, secondary Button text and outline color and Accordion trigger text', }, }, }, spacing: { 200: { value: '24px', type: 'spacing', description: 'Overrides core token used to define $sm Button padding and Accordion trigger padding', }, 300: { value: '32px', type: 'spacing', description: 'Overrides core token used to define $md/$lg Button padding', }, }, }, }; const semanticTheme = { web: { semantic: { color: { surface: { interactive: { standards: { hover: { default: { primary: { value: '#0053A6', type: 'color', description: 'Overrides semantic token used to define primary Button hover color', }, }, }, }, buttons: { hover: { cta: { value: '{core.color.brand.10}', type: 'color', description: 'Overrides semantic token used to define secondary Button hover color', }, }, }, }, }, }, sizing: { icon: { utility: { md: { value: '32px', type: 'sizing', description: 'Overrides semantic token used to define Accordion collapse chevron icon size and the Button icon size', }, }, }, width: { sm: { value: '36px', type: 'sizing', description: 'Overrides semantic token used to define $sm Button height', }, md: { value: '42px', type: 'sizing', description: 'Overrides semantic token used to define $md Button height', }, }, }, }, }, }; const Buttons = () => { return ( Home Home Home Small Medium Large Small Medium Large ); }; const Accordions = () => { return ( Sandbox Accordion 1 Sandbox Accordion 1 Content Sandbox Accordion 2 Sandbox Accordion 2 Content Sandbox Accordion 3 Sandbox Accordion 3 Content ); }; const overrideCode = { ...coreTheme, ...semanticTheme }; const flattenedTokens = flattenTokens(coreTheme, semanticTheme); render(() => { const currentTheme = useAbyssTheme(); const theme = createTheme(currentTheme.themeName, { theme: flattenedTokens }); const descriptions = useMemo( () => extractDescriptions(coreTheme, semanticTheme), [] ); const StyledList = styled('ul', { padding: '$sm', margin: '$sm', backgroundColor: '$core.color.neutral.0', listStyle: 'disc', }); return ( Original Theme Custom Theme Override Summary {descriptions.map((desc, index) => (

))} ); }); ``` ## Related links - [Theming/Styling Overview](/web/developers/theming-styling) - Token Documentation - [ThemeProvider Documentation](/web/ui/theme-provider) - createTheme Documentation --- id: is-valid-asset-name category: Util title: isValidAssetName description: Tool to verify the validity of an asset name. --- ```jsx import { isValidAssetName } from '@uhg-abyss/web/tools/isValidAssetName'; ``` The `isValidAssetName` tool is used to check if a given string is a valid asset name for a given component. Using this tool is only necessary when using TypeScript, as it provides type safety for asset names. The function has the following signature: ```ts type Component = | 'IconBrand' | 'IconMaterial' | 'IconSymbol' | 'IllustratedIconBrand' | 'IllustrationBrand'; const isValidAssetName: (name: string, component: Component) => boolean; ``` ## Usage `isValidAssetName` is primarily used as a way to contitionally render components if the asset name is valid. Try providing a value of `home` or `star` below to see this in action! ```jsx live () => { const [assetName, setAssetName] = React.useState(''); return ( { setAssetName(event.target.value); }} isClearable /> {isValidAssetName(assetName, 'IconSymbol') ? ( ) : ( 'Invalid IconSymbol Name' )} ); }; ``` --- id: styled category: Styling title: styled description: Tool to style elements. pagination_prev: null pagination_next: web/tools/config --- ```jsx import { styled } from '@uhg-abyss/web/tools/styled'; ``` ## Object syntax only Write CSS using the object style syntax. The reasons for this are: performance, bundle size and developer experience (type checks and autocomplete suggestions for both properties and values). ```jsx const Button = styled('button', { color: 'red', fontSize: '14px'; '&:hover': { color: 'black', fontSize: '14px'; }, }); ``` ## Chaining selectors All chained selectors require the `&` sign. ```jsx const Button = styled('button', { // all chained '&:hover': {}, '&::before': {}, '&.class': {}, }); ``` ## Prop interpolation vs variants You can conditionally apply variants at the consumption level, including at different breakpoints. ```jsx const Button = styled('button', { variants: { color: { violet: { backgroundColor: 'blueviolet' }, gray: { backgroundColor: 'gainsboro' }, }, }, }); () => ; ``` ## Tokens and themes You can define tokens in the createTheme config file and seamlessly consume and access them directly in the Style Object. See the Tokens documentation page for more information. ```jsx const Example = styled('div', { backgroundColor: '$core.color.brand.100', height: 100, width: 100, }); ``` ## Responsive styles You can access breakpoint tokens directly in the Style Object. ```jsx const Box = styled('div', { padding: '12px', '@screen >= $md': { padding: '24px', }, }); ``` ## Global styles You can add global styles with the globalStyles API. ```jsx import { globalCss } from '@uhg-abyss/web/tools/styled'; const globalStyles = globalCss({ body: { margin: '0', }, }); export function App() => { globalStyles(); return

Your app

} ``` ## Animations You can use the keyframes function to add animations ```jsx import { keyframes } from '@uhg-abyss/web/tools/styled'; const fadeIn = keyframes({ '0%': { opacity: '0' }, '100%': { opacity: '1' }, }); const Box = styled('div', { animationName: fadeIn, }); ``` ## Dynamic/static When Stitches variants won't work and the css you need is variable you can use the `static` and `dynamic` config in the `styled` tool. Place all of your static css along with variants, compoundVariants, and defaultVariants in the `static` config. The `dynamic` config takes in a function that returns any properties that are passed to the component. You can then use those props to handle dynamic styles like sizing and colors. For the best results and performance it is recommended to use variants when possible. ```jsx live const StyledDiv = styled('div', { static: { display: 'flex', alignItems: 'center', justifyContent: 'center', borderRadius: '10px', variants: { variant: { solid: { color: '$primary2', backgroundColor: '$primary1', border: 'solid 2px $primary1', }, outline: { color: '$primary1', backgroundColor: '$white', border: 'solid 2px $primary1', }, }, isDisabled: { true: { backgroundColor: '$gray3', color: '$gray5', borderColor: '$gray3', }, }, defaultVariants: { variant: 'solid', }, }, compoundVariants: [ { variant: 'solid', isDisabled: true, css: { backgroundColor: '$gray3', color: '$gray5', borderColor: '$gray3', cursor: 'not-allowed', }, }, ], }, dynamic: ({ cssProps }) => { const { size, fontSize } = cssProps; return { paddingTop: size + 6, paddingBottom: size + 6, paddingRight: size + 8, paddingLeft: size + 8, fontSize, }; }, }); render(() => { return ( Styled Div Component ); }); ``` ## Related links - [Theming/Styling Overview](/web/developers/theming-styling) - createTheme Documentation - Theme Token Overrides - [Styling with CSS Prop](/web/developers/theming-styling/#css-prop) --- id: accordion-v2 category: Content title: V2Accordion description: A vertically stacked list of headers that reveal or hide associated sections of content. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=24-313 subDirectory: Accordion/v2 sourceIsTS: true pagination_prev: null --- ```jsx render ``` ```jsx import { V2Accordion } from '@uhg-abyss/web/ui/Accordion'; ``` ```jsx sandbox { component: 'V2Accordion', inputs: [ { prop: 'type', type: 'select', options: [ { label: 'single', value: 'single' }, { label: 'multiple', value: 'multiple' }, ], }, { prop: 'defaultValue', type: 'select', options: [ { label: 'none', value: '' }, { label: 'sandbox-1', value: 'sandbox-1' }, { label: 'sandbox-2', value: 'sandbox-2' }, { label: 'sandbox-3', value: 'sandbox-3' }, ], }, { prop: 'isCollapsible', type: 'boolean', }, { prop: 'isDisabled', type: 'boolean', }, ] } Sandbox Accordion 1 SURPRISE - Sandbox Accordion 1 Sandbox Accordion 2 SURPRISE - Sandbox Accordion 2 Sandbox Accordion 3 SURPRISE - Sandbox Accordion 3 ``` ## Definitions (The terms in parentheses are the official names used by the WAI-ARIA) ### Accordion heading On `V2Accordion` use the `heading` prop to set a heading for the entire accordion component. Use the `headingLevel` prop to set the heading level. The default is set to `2` which renders the heading element as an `

`. It also holds the optional "Expand all / Collapse all" button, which is further defined in the section [Controlled expanded state](#controlled-expanded-state). ```jsx live () => { const accordionConfig = [ { value: 'sandbox-1', label: 'Sandbox Accordion 1' }, { value: 'sandbox-2', label: 'Sandbox Accordion 2' }, { value: 'sandbox-3', label: 'Sandbox Accordion 3' }, ]; return ( value)} > {accordionConfig.map(({ value, label }) => { return ( {label} SURPRISE - {label} ); })} ); }; ``` ### Accordion header - Label or thumbnail representing a section of content that also serves as a control for showing and, in some implementations, hiding the section of content. - Use the `headingLevel` prop available on `V2Accordion.Header` to set the heading level of the accordion item. The default is set to `3` which renders the heading element as an `

`. - Use the `icon` prop to add an [IconSymbol](/web/ui/icon-symbol) to the header. `icon` accepts a string (the name of the IconSymbol to use) or an object of the following type: ```ts { icon: string; variant: 'filled' | 'outlined'; } ``` ```jsx live Heading Level 2 Example The heading for this accordion item is set to level 2. Heading Level 3 Example (Default) The heading for this accordion item is set to level 3. Header with Icon This accordion header has an icon. ``` #### Nesting heading level correctly Whether the first heading of the V2Accordion is the main (group) heading or accordion header, make sure the component nests correctly in your main content. The `

` default for the (group) heading assumes it is a "top" level item that is one level below the primary `

` heading. The accordion headings default to `

` since it's assumed it will be part of a content section starting with `

` which can be the main content without a group heading. If these assumptions do not apply to where V2Accordion is nested in main page content, be sure to adjust the `headingLevel` prop to nest the (group) heading - if used - or the accordion header (if heading is not included). ### Accordion content (accordion panel) Section of content associated with an accordion header. Use prop `subheading` on `V2Accordion.Content` to add a subheading to the content area. ```jsx live Sandbox Accordion 1 SURPRISE - Sandbox Accordion 1 Sandbox Accordion 2 SURPRISE - Sandbox Accordion 2 Sandbox Accordion 3 SURPRISE - Sandbox Accordion 3 ``` ## Type and default value Use the `type` property to control whether the accordion can have one or multiple items open at a time. The possible values are `'single'` and `'multiple'`. The default is set to `'single'`. Use the `defaultValue` property to set which item or items are open by default. The value of `defaultValue` depends on the value of `type`. ### Single When `type` is set to `'single'`, `defaultValue` accepts a string. ```jsx live Is it accessible? Yes. It adheres to the WAI-ARIA design pattern. Is it unstyled? Yes. It's unstyled by default, giving you freedom over the look and feel. Can it be animated? Yes! You can animate the Accordion with CSS or JavaScript. ``` ### Multiple When `type` is set to `'multiple'`, `defaultValue` accepts an array of strings. ```jsx live Is it accessible? Yes. It adheres to the WAI-ARIA design pattern. Is it unstyled? Yes. It's unstyled by default, giving you freedom over the look and feel. Can it be animated? Yes! You can animate the Accordion with CSS or JavaScript. ``` ## Collapsible The `isCollapsible` property allows closing content when clicking the trigger for an open item when `type` is `'single'`. When `true`, all items can be collapsed. When `false`, one item will always remain open. The default is set to `false`. Note: When `type` is `'multiple'`, `isCollapsible` does not apply and is `undefined`. ```jsx live Is it accessible? Accordion Content 1 Is it unstyled? Accordion Content 2 Default Accordion Item 1 Accordion Content 1 Can it be animated? Accordion Content Item 2 ``` ## Trigger position Use the `triggerPosition` prop on `V2Accordion` to set the position of the trigger to the left or right of the accordion header. The default value is `'right'`. ```jsx live Left Position Item 1 Trigger position is on the left Left Position Item 2 Trigger position is on the left Left Position Item 3 Trigger position is on the left Right Position Item 1 Trigger position is on the right Right Position Item 2 Trigger position is on the right Right Position Item 3 Trigger position is on the right ``` ## Disabled Use the `isDisabled` property to disable the entire `V2Accordion` or individual items. The default is set to `false`. ```jsx live Item is not disabled Not disabled Item disabled Disabled Item is not disabled Not disabled Entire accordion is disabled Disabled Entire accordion is disabled Disabled ``` ## onValueChange The `onValueChange` property is an event handler that is called when the expanded state of any item changes. ```jsx live () => { const [multiValue, setMultiValue] = useState([]); const [singleValue, setSingleValue] = useState(''); const onValueChangeMulti = (e) => { console.log('Multi Value', e); setMultiValue(e); }; const onValueChangeSingle = (e) => { console.log('Single Value', e); setSingleValue(e); }; return ( Single Accordion Item 1 Accordion Content 1 Single Accordion Item 2 Accordion Content 2 Single Accordion Item 3 Accordion Content 3 Multiple Accordion Item 1 Accordion Content 1 Multiple Accordion Item 2 Accordion Content 2 Multiple Accordion Item 3 Accordion Content 3 ); }; ``` ## Controlled expanded state ### Expand all button When the accordion has `type` `'multiple'` and the `expandValues` prop is provided, an "Expand all / Collapse all" button will appear in the accordion heading. `expandValues` accepts an array of strings that correspond to the `value` of each `V2Accordion.Item` that should be expanded or collapsed when "Expand all / Collapse all" is clicked. For the optimal user experience, it is recommended you provide the values for all accordion items. ```jsx live () => { const accordionConfig = [ { value: 'sandbox-1', label: 'Sandbox Accordion 1' }, { value: 'sandbox-2', label: 'Sandbox Accordion 2' }, { value: 'sandbox-3', label: 'Sandbox Accordion 3' }, ]; return ( value)} > {accordionConfig.map(({ value, label }) => { return ( {label} SURPRISE - {label} ); })} ); }; ``` ### Custom controlled expanded state You can additionally control the expanded state of the accordion by using the `value` prop in combination with `onValueChange`. This allows you to programmatically control which items are expanded. ```jsx live () => { [expandedValues, setExpandedValues] = useState([]); const accordionConfig = [ { value: 'sandbox-1', label: 'Sandbox Accordion 1' }, { value: 'sandbox-2', label: 'Sandbox Accordion 2' }, { value: 'sandbox-3', label: 'Sandbox Accordion 3' }, ]; const isAllExpanded = useMemo(() => { return accordionConfig.every(({ value }) => { return expandedValues.includes(value); }); }, [expandedValues]); const handleExpandAll = () => { setExpandedValues( isAllExpanded ? [] : accordionConfig.map(({ value }) => value) ); }; return ( {isAllExpanded ? 'Collapse All' : 'Expand All'} {accordionConfig.map(({ value, label }) => { return ( {label} SURPRISE - {label} ); })} ); }; ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` An accordion is a vertically stacked set of interactive headings that each contain a title, content snippet, or thumbnail representing a section of content. The headings function as controls that enable users to reveal or hide their associated sections of content. Accordions are commonly used to reduce the need to scroll when presenting multiple sections of content on a single page. Adheres to the Accordion WAI-ARIA design pattern. Example . ```jsx live Is it accessible? Yes. It adheres to the WAI-ARIA design pattern. Is it unstyled? Yes. It's unstyled by default, giving you freedom over the look and feel. Can it be animated? Yes! You can animate the Accordion with CSS or JavaScript. ```
Reduced Motion
For users who have `prefers-reduced-motion` set to `reduced`, the animation of the spinning caret and expand/collapse is disabled. ```jsx render ```
Component Tokens
Note: Click on the token row to copy the token to your clipboard. ```jsx render ``` --- id: accordion category: Content title: Accordion description: A vertically stacked list of headers that reveal or hide associated sections of content. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=0-1188 subDirectory: Accordion/v1 --- ```jsx render ``` ```jsx import { Accordion } from '@uhg-abyss/web/ui/Accordion'; ``` ```jsx sandbox { component: 'Accordion', inputs: [ { prop: 'type', type: 'select', options: [ { label: 'single', value: 'single' }, { label: 'multiple', value: 'multiple' }, ], }, { prop: 'defaultValue', type: 'select', options: [ { label: 'none', value: '' }, { label: 'sandbox-1', value: 'sandbox-1' }, { label: 'sandbox-2', value: 'sandbox-2' }, { label: 'sandbox-3', value: 'sandbox-3' }, ], }, { prop: 'isCollapsible', type: 'boolean', }, { prop: 'isDisabled', type: 'boolean', }, ] } Sandbox Accordion 1 SUPRISE - Sandbox Accordion 1 Sandbox Accordion 2 SURPRISE - Sandbox Accordion 2 Sandbox Accordion 3 SURPRISE - Sandbox Accordion 3 ``` ## Definitions (The terms in parentheses are the official names used by the WAI-ARIA) ### Accordion trigger (accordion header) - Label or thumbnail representing a section of content that also serves as a control for showing and, in some implementations, hiding the section of content. - Use the `headingLevel` prop available on `Accordion.Trigger` to set the heading level of the accordion item. The default is set to `3` which renders the heading element as an `
`. ```jsx live Heading Level 2 Example The heading for this accordion item is set to level 2. Heading Level 3 Example (Default) The heading for this accordion item is set to level 3. ``` ### Accordion content (accordion panel) - Section of content associated with an accordion header. ## Type Use the `type` property to set the accordion to either have `single` or `multiple` open items. The default is set to `single`. ```jsx live Is it accessible? Yes. It adheres to the WAI-ARIA design pattern. Is it unstyled? Yes. It's unstyled by default, giving you freedom over the look and feel. Can it be animated Yes! You can animate the Accordion with CSS or JavaScript. ``` ## Default value - single Use the `defaultValue` property to set an initial accordion to be open based on its `value` property. When type is set to `single` pass in a string. ```jsx live Is it accessible? Yes. It adheres to the WAI-ARIA design pattern. Is it unstyled? Yes. It's unstyled by default, giving you freedom over the look and feel. Can it be animated? Yes! You can animate the Accordion with CSS or JavaScript. ``` ## Default value - multiple When the accordion `type` is set to `multiple`, pass in a string array. ```jsx live Is it accessible? Yes. It adheres to the WAI-ARIA design pattern. Is it unstyled? Yes. It's unstyled by default, giving you freedom over the look and feel. Can it be animated? Yes! You can animate the Accordion with CSS or JavaScript. ``` ## Collapsible The `isCollapsible` property allows closing content when clicking the trigger for an open item when the type is "single". When `true`, you are allowed to collapse all items. When `false`, one item will always remain open. The default is set to `false`. NOTE: When the type is "multiple", `isCollapsible` does not apply and is `undefined`. ```jsx live Is it accessible? Accordion Content 1 Is it unstyled? Accordion Content 2 Default Accordion Item 1 Accordion Content 1 Can it be animated? Accordion Content Item 2 ``` ## Disabled Use the `isDisabled` property to disable the entire `Accordion` or individual levels. The default is set to `false`. ```jsx live Item is not disabled Not disabled Item disabled Disabled Item is not disabled Not disabled Entire accordion is disabled Disabled Entire accordion is disabled Disabled ``` ## onValueChange The `onValueChange` property is an event handler that is called when the expanded state of any item changes. ```jsx live () => { const [multiValue, setMultiValue] = useState([]); const [singleValue, setSingleValue] = useState(''); const onValueChangeMulti = (e) => { console.log('Multi Value', e); setMultiValue(e); }; const onValueChangeSingle = (e) => { console.log('Single Value', e); setSingleValue(e); }; return ( Single Accordion Item 1 Accordion Content 1 Single Accordion Item 2 Accordion Content 2 Single Accordion Item 3 Accordion Content 3 Multiple Accordion Item 1 Accordion Content 1 Multiple Accordion Item 2 Accordion Content 2 Multiple Accordion Item 3 Accordion Content 3 ); }; ``` ## Controlled expanded state You can control the expanded state of the accordion by using the `value` prop in combination with `onValueChange`. This allows you to programmatically control which items are expanded. ```jsx live () => { [expandedValues, setExpandedValues] = useState([]); const accordionConfig = [ { value: 'sandbox-1', label: 'Sandbox Accordion 1' }, { value: 'sandbox-2', label: 'Sandbox Accordion 2' }, { value: 'sandbox-3', label: 'Sandbox Accordion 3' }, ]; const isAllExpanded = useMemo(() => { return accordionConfig.every(({ value }) => { return expandedValues.includes(value); }); }, [expandedValues]); const handleExpandAll = () => { setExpandedValues( isAllExpanded ? [] : accordionConfig.map(({ value }) => value) ); }; return ( {accordionConfig.map(({ value, label }) => { return ( {label} SUPRISE - {label} ); })} ); }; ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` An accordion is a vertically stacked set of interactive headings that each contain a title, content snippet, or thumbnail representing a section of content. The headings function as controls that enable users to reveal or hide their associated sections of content. Accordions are commonly used to reduce the need to scroll when presenting multiple sections of content on a single page. Adheres to the Accordion WAI-ARIA design pattern. Example . ```jsx live Is it accessible? Yes. It adheres to the WAI-ARIA design pattern. Is it unstyled? Yes. It's unstyled by default, giving you freedom over the look and feel. Can it be animated? Yes! You can animate the Accordion with CSS or JavaScript. ```
Reduced Motion
For users who have `prefers-reduced-motion` set to `reduced`, the animation of the spinning caret and expand/collapse is disabled. ```jsx render ``` --- id: accumulator-v2 category: Overlay title: V2Accumulator description: Accumulates and displays multiple loading states. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=13339-1325 sourceIsTS: true subDirectory: Accumulator --- ```jsx import { V2Accumulator } from '@uhg-abyss/web/ui/Accumulator'; ``` ## Overview The `V2Accumulator` component is designed to accumulate and display multiple loading states in a visually appealing manner. It provides a progress bar, summary information, and optional metadata, making it suitable for various use cases where tracking progress is essential. ```jsx live ``` ## Label and subText The `label` prop is used to display the main title of the accumulator, while the `subText` (optional) prop provides additional context or information related to the accumulator's state. Note: The `label` is rendered as an `h3` element by default, but you can change the heading level using the `headingLevel` prop. ```jsx live ``` ## Popover The `popover` (optional) prop allows you to provide additional information in a popover format. It includes a title and content, which can be used to give context or details about the accumulator's state. ```jsx live ``` ## Summary The `summary` prop is used to display a summary of the accumulator's state. It can include information such as the current value and target value, providing a quick overview of progress. Note: Even though both fields are open fields, it is recommended to use the `current` field to represent the current value and the `target` field to represent the target value as it helps maintain consistency across different accumulators. The example below shows how to use the `summary` prop effectively. ```jsx live ``` ## Percentage and showEndpoint - The `percentage` prop is used to indicate the progress of the accumulator. It should be a number between 0 and 100, representing the percentage of completion. - The `showEndpoint` prop, when set to `true`, displays the endpoint of the progress bar, providing a visual cue for the completion point. ```jsx live ``` ## Paragraph and metadata The `paragraph` (optional) prop allows you to add additional descriptive text to the accumulator, while the `metadata` (optional) prop can be used to display information such as the last updated date or other relevant details. ```jsx live ``` ## Badge - The `badge` (optional) prop allows you to display a badge under the progress bar. This uses our `V2Badge` component, which can be customized with different options (you can read more about it in the [V2Badge documentation](/web/ui/badge-v2)). Note: The badge will only be displayed if the `percentage` is 100. ```jsx live ``` ## Call to action (cta) The `cta` (optional) prop allows you to add a call to action button or link. It uses our [V2Link](/web/ui/link-v2) and [V2Button](/web/ui/button-v2) components. You need to pass a `type` prop with a value of `button` or `link`, and then provide the appropriate props for each type. ```jsx live alert('Button clicked!'), variant: 'outline', }} summary={{ current: '$100 spent of $100', target: '$100 remaining', }} percentage={100} /> ``` ```jsx render ``` ```jsx render ``` The `V2Accumulator` component is designed with accessibility in mind. It uses the `label` and `subText` props to provide clear context for screen readers. ```jsx live alert('More to learn!'), }} /> ```
Component Tokens
Note: Click on the token row to copy the token to your clipboard. ```jsx render ``` --- id: action-nav category: Navigation title: ActionNav description: Used to keep track of tasks as well as for navigation. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=2540-21341 --- ```jsx import { ActionNav } from '@uhg-abyss/web/ui/ActionNav'; ``` ```jsx render ``` ## ActionNav - The `title` prop can be used to change the title of the header card - The `subText` prop can be used to change the subText of the header card - The `headingLevel` prop can be used to change the headingLevel of the header card title. ```jsx live { console.log('onClick triggered'); }} actionText="5 Tasks Left" variant="warning" /> ``` ## Height Use the `height` prop to adjust the height of the ActionNav. The default size is set to 48px. ```jsx live { console.log('onClick triggered'); }} actionText="5 Tasks Left" variant="warning" /> { console.log('onClick triggered'); }} actionText="5 Tasks Left" variant="warning" /> { console.log('onClick triggered'); }} actionText="5 Tasks Left" variant="warning" /> ``` ## ActionNav.Item Use the `title` prop to set the title of the action item. ```jsx live { console.log('onClick triggered'); }} actionText="5 Tasks Left" variant="warning" /> ``` ```jsx live { console.log('onClick triggered'); }} actionText="1 Complete" variant="success" /> { console.log('onClick triggered'); }} actionText="1 Pending" variant="info" /> { console.log('onClick triggered'); }} actionText="1 Required Action" variant="warning" /> ``` ## Link ### ActionText Use the `actionText` prop to set the description for the action. ```jsx live { console.log('onClick triggered'); }} /> Task 2 } onClick={() => { console.log('onClick triggered'); }} actionText={ 2 Tasks Left These expire within 5 days. } variant="error" /> ``` ### Href - Use the `href` prop to set the link to a separate page. - Use the `openNewWindow` prop to open the link in a new window. ```jsx live ``` ### onClick Use the `onClick` prop to trigger a custom function when the actionText is clicked ```jsx live { console.log('onClick triggered'); }} actionText="5 Tasks Left" variant="warning" /> ``` ## Icons ### Custom icon Use the `icon` prop to pass in a specific `Icon` component. Find further guidance on material icons in the [Material Icons Tab](/web/ui/icon-material) and on accessibility within the [Accessibility Icons Section](/accessibility/#icons). ```jsx live } /> } /> ``` ### Hiding icon Use the `hideIcon` prop to disable the `Template`. The default is set to `false`. ```jsx live ``` ### Variants Use the `variant` prop to change the style of the type of icon that appears next to the `actionText`. Available variants include `'error'`, `'success'`, `'warning'` and `'info'`. The default is set to `'error'` ```jsx live ``` ## Icon title Use the `iconTitle` prop whenever additional meaning must be conveyed beyond what's provided by the action description. When used the icon is accessible by screen readers. For further guidance please see the [Accessibility Icons Section](/accessibility/#icons). ```jsx live { console.log('onClick triggered'); }} actionText="3 Tasks Left" variant="warning" iconTitle="Task includes warnings." /> ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ActionNav is a navigation tool that is used to keep track of tasks and navigate users to their tasks.
ActionNav.Item
ActionNav.Item is an item in the ActionNav. In order for the ActionNav items to be accessible by screen readers, each ActionNav.Item should have a unique title. If an icon is included the `iconTitle` prop should be used whenever additional meaning must be conveyed beyond what's provided by the action description. For further guidance please see the [Accessibility Icons Section](/accessibility/#icons). ```jsx live ```
Reduced Motion
Animations and transitions that have been changed when a user has `prefers-reduced-motion` set to `reduced`: - Animation of `Link` underline is removed ```jsx render ``` --- id: activity-tracker-v2 category: Data Display title: V2ActivityTracker description: Non-interactive visual component that displays activity progress over time. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=12519-1306 sourceIsTS: true subDirectory: ActivityTracker/v2 --- ```jsx import { V2ActivityTracker } from '@uhg-abyss/web/ui/ActivityTracker'; ``` ## Overview The `ActivityTracker` is designed to visually represent the completion of activities over a period of time, such as a week or two weeks. It displays a series of circles representing each day, with filled circles indicating completed days. ```jsx live () => { const completedDays = ['MON', 'TUE']; return ( ); }; ``` ## Variants Use the `variant` prop to determine which type of tracker you want to display. Depending on the variant, the component will accept different formats of `completedDays`. - `oneweek`: - The `completedDays` prop should be an array of strings representing the days of the week. - Accepted values for the `completedDays` prop are: `"SUN" | "MON" | "TUE" | "WED" | "THU" | "FRI" | "SAT"`. - `twoweek`: - The `completedDays` prop should be an array of strings representing the days of the 14-day period. - Accepted values for the `completedDays` prop are strings of numbers from `"1" to "14"`. ```jsx live () => { const completedOneWeek = ['MON', 'SUN']; const completedTwoWeeks = ['1', '2', '4', '9', '14']; return (

); }; ``` ## Show today Use the `showToday` prop to display the indicator for today's date. Note: This prop only applies for the `oneweek` variant. The default is set to `true`. ```jsx live () => { return (

); }; ``` ## Sizing Day visuals are evenly distributed in the main container. When the container resizes, the gap between elements grows or shrinks, and the visuals have a static size. It is recommended to use a container with a minimum size of `304px`. ```jsx live () => { const completedOneWeek = ['MON', 'SUN']; return (

); }; ``` ## Heading The `title` prop is used to display a heading for the activity tracker. It is rendered as an `h3` element by default, but you can change the heading level using the `headingLevel` prop. ```jsx live () => { const completedDays = ['MON', 'TUE']; return (

); }; ``` ```jsx render ``` ```jsx render ``` V2ActivityTracker is a non-interactive visual representation of an activity over time that helps people monitor progress and patterns.
ARIA Labels
Incomplete days have different ARIA labels depending on if the day is in the past or in the future:

In the past, the ARIA label would announce the name of the day and followed with “incomplete”

In the future, the ARIA label will announce only the name of the day

This only applies to the weekly tracker # ```jsx live () => { const completedDays = ['MON', 'TUE']; const completedLastWeek = ['SUN', 'MON', 'TUE', 'FRI', 'SAT']; const completedTwoWeeks = ['1', '2', '4', '9', '14']; return (

); }; ```
Known BrAT Issues
- MacOS: VoiceOver and Safari (WebKit) - Ignores `aria-hidden` setting for entries - Announces offscreen content for: - Status icon - 3-letter day abbreviation (1-week variant) - Number (2-week variant) - New line - Appears to be a known issue with older versions of VoiceOver (See: Known issues | a11y-dialog) - VoiceOver and Chrome announce correctly
Component Tokens
Note: Click on the token row to copy the token to your clipboard. ```jsx render ``` --- id: activity-tracker category: Data Display title: ActivityTracker sourceIsTS: true description: Non-interactive visual component that displays activity progress over time. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=71940-1160 subDirectory: ActivityTracker/v1 --- ```jsx import { ActivityTracker } from '@uhg-abyss/web/ui/ActivityTracker'; ``` ## Usage ```jsx live () => { const completedDays = ['MON', 'TUE']; return ( ); }; ``` ## Variants Use the `variant` prop to determine the variant of the activity tracker. The `oneweek` variant tracks weekly progress, while the `twoweeks` variant tracks 14-day progress. The `oneweek` variant is the default. Depending on the variant, the component will accept different formats of `completedDays`. - For the `oneweek` variant: - The `completedDays` prop should be an array of strings representing the days of the week. - Accepted values for the `completedDays` prop are: "SUN", "MON", "TUE", "WED", "THU", "FRI", and "SAT". - For the `twoweek` variant: - The `completedDays` prop should be an array of strings representing the days of the 14-day period. - Accepted values for the `completedDays` prop are strings of numbers from "1" to "14". ```jsx live () => { const completedOneWeek = ['MON', 'SUN']; const completedTwoWeeks = ['1', '2', '4', '9', '14']; return (

); }; ``` ## showToday Use the `showToday` prop to display the indicator for today's date. This prop does not apply for the `twoweeks` variant. The default is set to `true`. ```jsx live () => { return (

); }; ``` ## Resizing Day visuals are evenly distributed in the main container. When the container resizes, the gap between elements grows or shrinks, and the visuals have a static size. It is recommended to use a container with a minimum size of `380px`. ```jsx live () => { const completedOneWeek = ['MON', 'SUN']; return (

); }; ``` ```jsx render ``` ```jsx render ``` ActivityTracker is a non-interactive visual representation of an activity over time, that helps people monitor progress and patterns.
ARIA Labels
Incomplete days have different ARIA labels depending on if the day is in the past or in the future:

In the past, the ARIA label will announce the name of the day and follows with “incomplete”

In the future, the ARIA label will announce only the name of the day

This only applies to the weekly tracker # ```jsx live () => { const completedDays = ['MON', 'TUE']; const completedLastWeek = ['SUN', 'MON', 'TUE', 'FRI', 'SAT']; const completedTwoWeeks = ['1', '2', '4', '9', '14']; return (

); }; ```
Known BrAT Issues
- MacOS: VoiceOver and Safari (WebKit) - Ignores `aria-hidden` setting for entries - Announces offscreen content for: - Status icon - 3-letter day abbreviation (1-week variant) - Number (2-week variant) - New line - Appears to be a known issue with older version of VoiceOver (See: Known issues | a11y-dialog) - VoiceOver and Chrome announce correctly --- id: alert-v2 category: Feedback title: V2Alert description: Provides a brief application status message. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=10548-3914 subDirectory: Alert/v2 sourceIsTS: true --- ```jsx render ``` ```jsx import { V2Alert } from '@uhg-abyss/web/ui/Alert'; ``` ```jsx sandbox { component: 'V2Alert', inputs: [ { prop: 'title', type: 'string', }, { prop: 'children', type: 'string', }, { prop: 'status', type: 'select', options: [ { label: 'error', value: 'error' }, { label: 'info', value: 'info' }, { label: 'success', value: 'success' }, { label: 'warning', value: 'warning' }, ], }, { prop: 'dismissible', type: 'boolean', }, { prop: 'showDivider', type: 'boolean', }, { prop: 'inline', type: 'boolean', }, ] } Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. ``` ## Title Use the `title` prop to set the title of the Alert. A `title` is not required. By default, the title is rendered as an `
`, but this can be configured using the `headingLevel` prop. ```jsx live () => { const [visibleAlerts, setVisibleAlerts] = useState([true, true, true]); const resetButtonRef = useRef(null); return ( { setVisibleAlerts([true, true, true]); }} > Reset Alerts { setVisibleAlerts([false, visibleAlerts[1], visibleAlerts[2]]); resetButtonRef.current?.focus(); }} > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. { setVisibleAlerts([visibleAlerts[0], false, visibleAlerts[2]]); resetButtonRef.current?.focus(); }} > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. { setVisibleAlerts([visibleAlerts[0], visibleAlerts[1], false]); resetButtonRef.current?.focus(); }} > This Alert has no title. ); }; ``` ## Content The children of the Alert will be displayed as the main content. The content can only be a string and is limited to 100 characters in length. ```jsx live () => { const [isVisible, setIsVisible] = useState(true); const resetButtonRef = useRef(null); return ( { setIsVisible(true); }} > Reset Alert { setIsVisible(false); resetButtonRef.current?.focus(); }} > Text is placed here. ); }; ``` ## Status Use the `status` prop to change the style of the Alert. The available options are `'error'`, `'info'`, `'success'`, and `'warning'`. The default value is `'error'`. ```jsx live () => { const [visibleAlerts, setVisibleAlerts] = useState([true, true, true, true]); const resetButtonRef = useRef(null); return ( { setVisibleAlerts([true, true, true, true]); }} > Reset Alerts { setVisibleAlerts([ false, visibleAlerts[1], visibleAlerts[2], visibleAlerts[3], ]); resetButtonRef.current?.focus(); }} > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. { setVisibleAlerts([ visibleAlerts[0], false, visibleAlerts[2], visibleAlerts[3], ]); resetButtonRef.current?.focus(); }} > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. { setVisibleAlerts([ visibleAlerts[0], visibleAlerts[1], false, visibleAlerts[3], ]); resetButtonRef.current?.focus(); }} > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. { setVisibleAlerts([ visibleAlerts[0], visibleAlerts[1], visibleAlerts[2], false, ]); resetButtonRef.current?.focus(); }} > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. ); }; ``` ## CTA Use the `cta` prop to add a call to action to the Alert. The `cta` prop accepts an object of the following type: ```ts { type: 'button' | 'link', props: V2ButtonProps | V2LinkProps, } ``` `V2ButtonProps` and `V2LinkProps` are objects that accept most props of the [V2Button](/web/ui/button-v2) and [V2Link](/web/ui/link-v2) components, respectively, except for `size`, which is set by the Alert and cannot be altered. ```jsx live () => { const [visibleAlerts, setVisibleAlerts] = useState([true, true]); const resetButtonRef = useRef(null); return ( { setVisibleAlerts([true, true]); }} > Reset Alerts { setVisibleAlerts([false, visibleAlerts[1]]); resetButtonRef.current?.focus(); }} cta={{ type: 'button', props: { children: 'Button', onClick: () => { console.log('CTA button clicked'); }, }, }} > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. { setVisibleAlerts([visibleAlerts[0], false]); resetButtonRef.current?.focus(); }} cta={{ type: 'link', props: { children: 'Link', href: '#cta', onClick: () => { console.log('CTA link clicked'); }, }, }} > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. ); }; ``` ## Programmatically displaying alerts Use the `isVisible` prop to control whether the Alert is displayed. The default value is `true`. ```jsx live () => { const [isVisible, setIsVisible] = useState(true); const toggleButtonRef = useRef(null); const toggleVisibility = () => { setIsVisible(!isVisible); }; return ( Toggle Alert { setIsVisible(false); toggleButtonRef.current?.focus(); }} > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. ); }; ``` ## Dismissible Use the `dismissible` prop to control whether the Alert can be closed manually. The default value is `true`. This prop must be used in conjunction with `isVisible` and `onClose` to work properly. ```jsx live () => { const [visibleAlerts, setVisibleAlerts] = useState([true, true]); const resetButtonRef = useRef(null); return ( { setVisibleAlerts([visibleAlerts[0], !visibleAlerts[1]]); }} > Toggle Non-Dismissible Alert { setVisibleAlerts([true, true]); }} > Reset Alerts { setVisibleAlerts([false, visibleAlerts[1]]); resetButtonRef.current?.focus(); }} > This Alert can be dismissed manually. This Alert cannot be dismissed manually. ); }; ``` ## onClose Use the `onClose` prop to execute a custom callback when the Alert is closed. Note: `onClose` is only executed when the close button is clicked (i.e., when `dismissible` is `true`). It is not executed when the Alert is closed programmatically. ```jsx live () => { const [isVisible, setIsVisible] = useState(true); const toggleButtonRef = useRef(null); const toggleVisibility = () => { setIsVisible(!isVisible); }; return ( Toggle Alert { console.log('Alert closed'); setIsVisible(false); toggleButtonRef.current?.focus(); }} > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. ); }; ``` ## Show divider Use the `showDivider` prop to control whether a divider is shown before the close button. The default value is `true`. This prop is only used when `dismissible` is `true`. Note: Since the [inline variant](#inline) does not use a divider, this prop has no effect when `inline` is `true`. ```jsx live () => { const [visibleAlerts, setVisibleAlerts] = useState([true, true]); const resetButtonRef = useRef(null); return ( { setVisibleAlerts([true, true]); }} > Reset Alerts { setVisibleAlerts([false, visibleAlerts[1]]); resetButtonRef.current?.focus(); }} showDivider={false} > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. { setVisibleAlerts([visibleAlerts[0], false]); resetButtonRef.current?.focus(); }} > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. ); }; ``` ## Timestamp Use the `timestamp` prop to display a timestamp below the content of the Alert. Note: This example uses the [Day.js library](/web/tools/dayjs/) to format the timestamp, but you're free to use any method you like. We recommend using Day.js, though, as it is easy to use, very readable, and already included with Abyss. Timestamps can automatically be formatted based on the user's locale using the `LocalizedFormat` plugin. ```jsx live () => { const [isVisible, setIsVisible] = useState(true); const toggleButtonRef = useRef(null); return ( { setIsVisible(!isVisible); }} > Toggle Alert { setIsVisible(false); toggleButtonRef.current?.focus(); }} > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. ); }; ``` ## Inline Use the `inline` prop to display Alert as an inline element instead of as a banner. The default value is `false`. ```jsx live () => { const [visibleAlerts, setVisibleAlerts] = useState([true, true]); const resetButtonRef = useRef(null); return ( { setVisibleAlerts([true, true]); }} > Reset Alerts { setVisibleAlerts([false, visibleAlerts[1]]); resetButtonRef.current?.focus(); }} cta={{ type: 'button', props: { children: 'Button', onClick: () => { console.log('CTA button clicked'); }, }, }} > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. { setVisibleAlerts([visibleAlerts[0], false]); resetButtonRef.current?.focus(); }} cta={{ type: 'button', props: { children: 'Button', onClick: () => { console.log('CTA button clicked'); }, }, }} > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. ); }; ``` ## Accessibility Use the `ariaText` prop to provide additional information denoted by the color/status. This will be announced before visible text. For more information, visit the [Accessibility tab](/web/ui/alert-v2?tab=accessibility). ```jsx live () => { const [isVisible, setIsVisible] = useState(true); const resetButtonRef = useRef(null); return ( { setIsVisible(true); }} > Reset Alert { setIsVisible(false); resetButtonRef.current?.focus(); }} > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. ); }; ``` ## Responsiveness On screens less than 744px wide, the Alert will adjust its layout. Resize the window to see the change! ```jsx live () => { const [isVisible, setIsVisible] = useState(true); const toggleButtonRef = useRef(null); return ( { setIsVisible(!isVisible); }} > Toggle Alert { setIsVisible(false); toggleButtonRef.current?.focus(); }} cta={{ type: 'button', props: { children: 'Button', onClick: () => { console.log('CTA button clicked'); }, }, }} > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. ); }; ``` ```jsx render ``` ```jsx render ``` An alert is an element that displays a brief, important message in a way that attracts the user's attention without interrupting the user's task. Dynamically rendered alerts are automatically announced by most screen readers, and in some operating systems, they may trigger an alert sound. It is important to note that, at this time, screen readers do not inform users of alerts that are present on the page before the page load completes. Adheres to the WAI-ARIA Alert design pattern. The Alert Example provided by W3.org demonstrates the Alert Pattern. ```jsx live () => { const [visibleAlerts, setVisibleAlerts] = useState([true, true, true, true]); const resetButtonRef = useRef(null); return ( { setVisibleAlerts([true, true, true, true]); }} > Reset Alerts { setVisibleAlerts([ visibleAlerts[0], !visibleAlerts[1], visibleAlerts[2], visibleAlerts[3], ]); resetButtonRef.current?.focus(); }} > Toggle Info Alert { setVisibleAlerts([ false, visibleAlerts[1], visibleAlerts[2], visibleAlerts[3], ]); resetButtonRef.current?.focus(); }} > We are working to restore site operations and should be back soon. { setVisibleAlerts([ visibleAlerts[0], false, visibleAlerts[2], visibleAlerts[3], ]); resetButtonRef.current?.focus(); }} > Regular business hours are 8:00AM to 8:00PM Central Time (USA). { setVisibleAlerts([ visibleAlerts[0], visibleAlerts[1], false, visibleAlerts[3], ]); resetButtonRef.current?.focus(); }} cta={{ type: 'button', props: { children: 'Receive notifications', onClick: () => { console.log('CTA button clicked'); }, }, }} > All information successfully received. We will contact you when your claim is updated { setVisibleAlerts([ visibleAlerts[0], visibleAlerts[1], visibleAlerts[2], false, ]); resetButtonRef.current?.focus(); }} cta={{ type: 'link', props: { children: 'Live support', href: '#cta', onClick: () => { console.log('CTA link clicked'); }, }, }} > Due to technical difficulties responses may be delay one to two working days. Live support options can help get your answers sooner. ); }; ``` ```jsx render ```
Decorative Icons
The brand icon in the Emphasis Banner is considered decorative and does not require a text alternative, though one can be provided if desired.
Close Button Guidance
If the close button is present—which it is by default—it must be keyboard accessible. A keyboard-only user must be able to tab to the button and activate it with the space bar and the enter key. When the Alert is closed, focus must be placed back where it previously was on the page.
ARIA Properties
If `status` is `'success'` or `'info'`, `V2Alert` has the following ARIA properties: - `role="status"` - `aria-live="polite"` If `status` is `'warning'` or `'error'`, `V2Alert` has the following ARIA properties: - `role="alert"`
BrAT Variant Behaviors
- JAWS - Only announces text - Does not announce actions or close button - NVDA, VoiceOver - Both announce all contents, though not roles (link, button)
Component Tokens
Note: Click on the token row to copy the token to your clipboard. ```jsx render ``` --- id: alert category: Feedback title: Alert description: Provides a brief message about the app processes. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=0-985 subDirectory: Alert/v1 --- ```jsx render ``` ```jsx import { Alert } from '@uhg-abyss/web/ui/Alert'; ``` ```jsx sandbox { component: 'Alert', inputs: [ { prop: 'title', type: 'string', }, { prop: 'children', type: 'string', }, { prop: 'variant', type: 'select', options: [ { label: 'error', value: 'error' }, { label: 'success', value: 'success' }, { label: 'info', value: 'info' }, { label: 'warning', value: 'warning' }, ], }, { prop: 'hideIcon', type: 'boolean', }, ] } Alert Sandbox Content ``` ## Children Add Children to the `Alert` component by simply placing elements between the `Alert` tags. Children should be used for adding description text or any additional content you'd like to display below the title. ```jsx live () => { const [isVisible, setIsVisible] = useState(true); const buttonRef = useRef(); const toggleVisibility = () => { setIsVisible(!isVisible); }; return ( { setIsVisible(false); if (buttonRef.current) { buttonRef.current.focus(); } }} > Description text or whatever additional content you’d like to display below the title goes here. ); }; ``` ## Variants Use the `variant` property to change the style of the `Alert`. Available variants include `'error'`, `'success'`, `'warning'` and `'info'`. The default is set to `'error'` ```jsx live () => { const [isVisible, setIsVisible] = useState(true); const buttonRef = useRef(); const toggleVisibility = () => { setIsVisible(!isVisible); }; return ( { setIsVisible(false); if (buttonRef.current) { buttonRef.current.focus(); } }} /> { setIsVisible(false); if (buttonRef.current) { buttonRef.current.focus(); } }} /> { setIsVisible(false); if (buttonRef.current) { buttonRef.current.focus(); } }} /> { setIsVisible(false); if (buttonRef.current) { buttonRef.current.focus(); } }} /> ); }; ``` ## Change icon Use the `icon` property to pass in a specific `Icon` component. If the icon is being used in a setting in which it is just a decorative element (which is the default case for icons), then the icon should be ignored by screen readers. The implementation below provides an example of a situation that would be classified as decorative. Since the default of `isScreenReadable` is set to false no specific changes need to be made for decorative icons. Find further guidance on material icons in the [Material Icons Tab](/web/ui/icon-material). ```jsx live () => { const [isVisible, setIsVisible] = useState(true); const buttonRef = useRef(); const toggleVisibility = () => { setIsVisible(!isVisible); }; return ( } title="Search Information" variant="info" isVisible={isVisible} onClose={() => { setIsVisible(false); if (buttonRef.current) { buttonRef.current.focus(); } }} /> ); }; ```
If the icon is being used in a setting where it is the only element providing meaning, then that same meaning should be conveyed to screen reader users. The implementation below provides an example in which the property `isScreenReadable` should be set to true and the `title` property is required and should describe the purpose of the image. Find further guidance on material icons in the [Material Icons Tab](/web/ui/icon-material). ```jsx live () => { const [isVisible, setIsVisible] = useState(true); const buttonRef = useRef(); const toggleVisibility = () => { setIsVisible(!isVisible); }; return ( } title="Text" variant="info" isVisible={isVisible} onClose={() => { setIsVisible(false); if (buttonRef.current) { buttonRef.current.focus(); } }} /> ); }; ``` ## Hide icon Use the `hideIcon` property to disable the `Template`. The default is set to `false`. ```jsx live () => { const [isVisible, setIsVisible] = useState(true); const buttonRef = useRef(); const toggleVisibility = () => { setIsVisible(!isVisible); }; return ( { setIsVisible(false); if (buttonRef.current) { buttonRef.current.focus(); } }} /> ); }; ``` ## Title Use the `title` property to set the title for the alert. ```jsx live () => { const [isVisible, setIsVisible] = useState(true); const buttonRef = useRef(); const toggleVisibility = () => { setIsVisible(!isVisible); }; return ( { setIsVisible(false); if (buttonRef.current) { buttonRef.current.focus(); } }} /> ); }; ``` ## Icon screen readable and icon title Use the `isIconScreenReadable` property to make the alert variant icon discoverable by assistive technology. The `isIconScreenReable` property should be used if the meaning of the alert is not given using adjacent text, and the decorative variant icon becomes meaningful. If the variant icon becomes meaningful, use the `iconTitle` property to set a title for the variant icon that conveys the meaning or content that is displayed visually. For more information on meaningful and decorative icons can be found under the accessibility tab. ```jsx live () => { const [isVisible, setIsVisible] = useState(true); const buttonRef = useRef(); const toggleVisibility = () => { setIsVisible(!isVisible); }; return ( { setIsVisible(false); if (buttonRef.current) { buttonRef.current.focus(); } }} /> { setIsVisible(false); if (buttonRef.current) { buttonRef.current.focus(); } }} /> ); }; ``` ## onClose Use the `onClose` property to handle the action when close button is triggered. The `onClose` property is always required. ```jsx live () => { const [isVisible, setIsVisible] = useState(true); const buttonRef = useRef(); const toggleVisibility = () => { setIsVisible(!isVisible); }; return ( { setIsVisible(false); if (buttonRef.current) { buttonRef.current.focus(); } }} /> ); }; ``` ## onAction Use the `onAction` property to handle a custom event when the action button is triggered. Use the `actionText` property to set the text inside the action button. ```jsx live () => { const [isVisible, setIsVisible] = useState(true); const buttonRef = useRef(); const toggleVisibility = () => { setIsVisible(!isVisible); }; return ( { console.log('Action Triggered'); }} actionText="Custom Action" isVisible={isVisible} variant="warning" onClose={() => { setIsVisible(false); if (buttonRef.current) { buttonRef.current.focus(); } }} > Action button with custom event ); }; ``` ## actionHref Use the `actionHref` property to link away to another page when it is clicked. Use the `actionText` property to set the text inside the action link. When using an href if the link is external or the `openNewWindow` prop is set to true the action link will open in a new window. ```jsx live () => { const [isVisible, setIsVisible] = useState(true); const buttonRef = useRef(); const toggleVisibility = () => { setIsVisible(!isVisible); }; return ( { setIsVisible(false); if (buttonRef.current) { buttonRef.current.focus(); } }} > Action button with link { setIsVisible(false); if (buttonRef.current) { buttonRef.current.focus(); } }} > Action button with link open in new window ); }; ``` ## Error code Use the `errorCode` property to display an error code that is appended with the current date/time. ```jsx live () => { const [isVisible, setIsVisible] = useState(true); const buttonRef = useRef(); const toggleVisibility = () => { setIsVisible(!isVisible); }; return ( { setIsVisible(false); if (buttonRef.current) { buttonRef.current.focus(); } }} /> ); }; ``` ## Timezone Use the `timezone` property to change the timezone of the alert timestamp. The default is set to `'America/Chicago'`. A comprehensive list of valid timezones can be found here. ```jsx live () => { const [isVisible, setIsVisible] = useState(true); const buttonRef = useRef(); const toggleVisibility = () => { setIsVisible(!isVisible); }; return ( { setIsVisible(false); if (buttonRef.current) { buttonRef.current.focus(); } }} /> { setIsVisible(false); if (buttonRef.current) { buttonRef.current.focus(); } }} /> { setIsVisible(false); if (buttonRef.current) { buttonRef.current.focus(); } }} /> ); }; ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` An alert is an element that displays a brief, important message in a way that attracts the user's attention without interrupting the user's task. Dynamically rendered alerts are automatically announced by most screen readers, and in some operating systems, they may trigger an alert sound. It is important to note that, at this time, screen readers do not inform users of alerts that are present on the page before page load completes. Adheres to the Alert WAI-ARIA design pattern. The Alert Example provided by W3.org demonstrates the Alert Pattern. ```jsx render ``` Note: Warning color currently does not meeting 3:1 contrast #### Meaningful or Control Icons If an alert with an icon conveys information that is not conveyed by title text, the icon is considered meaningful (not decorative) and must have a text alternative. #### Decorative Icons In alerts with sufficient text next to the icon, the icon is considered decorative and and does not need to be exposed to assistive technology. #### Close Button Guidance Keyboard operation: if the “close” button is used on the alert, it must be keyboard accessible. A keyboard only user must be able to tab to the button, and activate it with the space bar and the enter key. When the alert is closed, focus must be placed back to the element that caused it to open or where it previously was on the page. Note: per the WAI ARIA specification, when the “alert” role is used, the user should not be required to close the alert. In this case, it is assumed that the close button is provided as a convenience and the user is not explicitly required to close the alert. #### Alert Variants For the success and info variants, we want `role = "status"` and `aria-live = "polite"`. For the warning and error variants, we want `role="alert"` with no aria-live or explicitly assertive (`aria-live="assertive"`) #### Accepted BrAT Variant Behaviors - JAWS - Only announces text - Does not announce actions or close button - NVDA, VoiceOver - Both announce all contents though not roles (link, button) --- id: avatar-v2 category: Data Display title: V2Avatar description: The Avatar component is used to represent a user, and displays the profile picture or the user initials as content. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=12465-505 subDirectory: Avatar/v2 sourceIsTS: true --- ```jsx render ``` ```jsx import { V2Avatar } from '@uhg-abyss/web/ui/Avatar'; ``` ```jsx sandbox { component: 'V2Avatar', inputs: [ { prop: 'children', type: 'string', }, { prop: 'variant', type: 'select', options: [ { label: '1', value: 1 }, { label: '2', value: 2 }, { label: '3', value: 3 }, { label: '4', value: 4 }, { label: '5', value: 5 }, ] }, ] } JA ``` ## Clicking the avatar By default, the Avatar component is read-only, but can be made interactive by configuring it as a button or link. Use the `href` prop to create a link avatar (renders as an anchor tag) and the `onClick` prop to create a button avatar (renders as a button element). The `type` prop can be used to specify the button type when using `onClick`. When interactive, the Avatar receives focus styles and proper keyboard navigation support. ```jsx live TB Tony Braasch As Link console.log('avatar was clicked!')}> EP Esteban Palacio As Button ``` ## Avatar image and children Use the `src` and `alt` props to set the Avatar image source and alternate name. If the image cannot be loaded or is not provided, the Avatar will display a placeholder instead. By default, the placeholder is the `IconSymbol` "person" icon. Children for the Avatar accepts either a React node or a string. If a string is provided, it will be modified to display the first two characters in uppercase. ```jsx live JA ``` ## Color variants Use the `variant` prop to set the color of the Avatar. The available variants are `1`, `2`, `3`, `4`, and `5`. Each variant has a different color scheme. ```jsx live JA JA JA JA JA ``` ## Notification Use the [V2Indicator](/web/ui/indicator-v2) component in combination with the Avatar to display a notification. When an indicator is used on a focusable Avatar, make sure to use the `ariaLabel` prop to provide context to screen readers. ```jsx live () => { const [notifications, setNotification] = useState(1); return ( console.log('there is a notification')} ariaLabel={`avatar with ${notifications} notification(s) indicated`} /> JA ); }; ``` ## Aria label Use the `ariaLabel` prop to provide an accessible name. If an `ariaLabel` is not provided, by default it will read as `avatar` for images and icons, and `X Y avatar` for lettered avatars. ```jsx live JA ``` ```jsx render ``` ```jsx render ``` Avatars are not focusable, use the `ariaLabel` prop for providing an accessible name. If an `ariaLabel` is not provided, by default it will read as `avatar` for images and icons. For initial lettered avatars it will read as `X Y avatar`. #### Aria Label Below is an example usage of passing `ariaLabel` to different avatar types. ```jsx live () => { return ( JA JA console.log('there is a notification')} ariaLabel={'Your avatar'} variant={4} size="60px" > ); }; ```
Component Tokens
Note: Click on the token row to copy the token to your clipboard. ```jsx render ``` --- id: avatar category: Data Display title: Avatar description: The Avatar component is used to represent a user, and displays the profile picture or the user initials as content. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=36878-120337 subDirectory: Avatar/v1 --- ```jsx import { Avatar } from '@uhg-abyss/web/ui/Avatar'; ``` ```jsx sandbox { component: 'Avatar', inputs: [ { prop: 'children', type: 'string', }, { prop: 'size', type: 'string', }, { prop: 'variant', type: 'select', options: [ { label: 'outline', value: 'outline' }, { label: 'solid', value: 'solid' }, ], }, { prop: 'colorTheme', type: 'select', options: [ { label: 'aqua', value: 'aqua' }, { label: 'mint', value: 'mint' }, { label: 'peach', value: 'peach' }, { label: 'skyBlue', value: 'skyBlue' }, ] }, ] } JA ``` ## Variants Use the `variant` prop to change the variant of the Avatar. The options are `outline`, `solid`. The default value is `outline`. - Outline: Best utilized against dark backgrounds - Solid: Best utilized against light backgrounds ```jsx live JA John Adams Home JA John Adams Home ``` ## Avatar image Use the `src` and `alt` props to set the Avatar image source and alternate name. If the image cannot be loaded or is not provided, the Avatar will display a placeholder instead. By default, the placeholder is the IconSymbol "account_circle" icon, but it can be changed to any React node. ```jsx live ``` ## Color theme Use the `colorTheme` prop to set the color of the Avatar. The options are `aqua`, `mint`, `peach`, and `skyBlue`. The default is `aqua`. The `colorTheme` prop only effects the `outline` variant. ```jsx live JA JA JA JA ``` ## Size Use the `size` prop to change the size of the Avatar. The default is set to `40px` || `$md`. The size prop can take in px, rem, em and the Abyss standardized $sm, $md, and $lg tokens. ```jsx live JA JA JA JA JA JA JA JA ``` ## Children Children for the Avatar accepts either a React node or a string. If a string is provided, it will be modified to display the first two characters in uppercase. ```jsx live JA ``` ## Notification Use the [Indicator](/web/ui/indicator) component in combination with the Avatar to display a notification. ```jsx live JA ``` ## Aria label Use the `ariaLabel` prop to provide an accessible name. If an `ariaLabel` is not provided, by default it will read as `avatar` for images and icons, and `X Y avatar` for lettered avatars. ```jsx live JA ``` ```jsx render ``` ```jsx render ``` Avatars are not focusable, use the `ariaLabel` prop for providing an accessible name. If an `ariaLabel` is not provided, by default it will read as `avatar` for images and icons. For initial lettered avatars it will read as `X Y avatar`. #### Aria Label Below is an example usage of passing `ariaLabel` to different avatar types. ```jsx live JA ``` --- id: badge-v2 category: Data Display title: V2Badge description: Provides a small descriptor for UI elements. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=3-21872 subDirectory: Badge/v2 sourceIsTS: true --- ```jsx render ``` ```jsx import { V2Badge } from '@uhg-abyss/web/ui/Badge'; ``` ```jsx sandbox { component: 'V2Badge', inputs: [ { prop: 'children', type: 'string', }, { prop: 'variant', type: 'select', options: [ { label: 'success', value: 'success' }, { label: 'warning', value: 'warning' }, { label: 'error', value: 'error' }, { label: 'info', value: 'info' }, { label: 'neutral', value: 'neutral' }, ] }, { prop: 'outline', type: 'boolean', }, ] } V2Badge Sandbox ``` ## Variants Use the `variant` property to set the color of the `V2Badge`. The options are `'success'`, `'warning'`, `'error'`, `'info'`, and `'neutral'`. The default is `'success'`. ```jsx live Success Badge Warning Badge Error Badge Info Badge Neutral Badge Success Badge Warning Badge Error Badge Info Badge Neutral Badge ``` ## Outline Use the `outline` property to turn on the outline of the `V2Badge`. The default is `false`. ```jsx live Badge Outline Badge ``` ## Icons To insert an [IconSymbol](/web/ui/icon-symbol) into the `V2Badge`, use the `icon` property. The `icon` prop accepts either a string (the name of the IconSymbol to use) or an object of the following type: ```ts { icon: string; variant: 'filled' | 'outlined'; } ``` See the [IconSymbol](/web/ui/icon-symbol#symbol-icon-variants) docs for more info on the possible variants. ```jsx live Error Warning Success Info Neutral ``` ## Width The `V2Badge` component has a max width of 200px. Excess text will truncate. ```jsx live Max width of 200 pixels. Excess text will truncate. ``` ## Accessibility Use the `ariaText` prop to provide additional information denoted by the color. This will be announced before visible text. For more information, visit the [Accessibility tab](/web/ui/badge-v2?tab=accessibility). ```jsx live Password validation 12+ characters Upper & lower case Number(s) Special character(s) ``` ```jsx render ``` ```jsx render ``` Badges are not focusable, visual text elements used to show a status for quick recognition. Avoid using badge for text truncated beyond 200 pixels, because it will not be accessible. #### Decorative Icons In the badge below, since there is sufficient text next to the icon, the icon is considered decorative and and does not need to be exposed to assistive technology. ```jsx live Warning ``` #### Meaningful Colors Conveying Meaning Via Color Alone: Color must not used as the only means of conveying information, actions, prompting a response, or distinguishing elements. Using color to add meaning only provides a visual indication, which will not be conveyed to users of assistive technologies – such as screen readers. Ensure that information denoted by the color is either obvious from the content itself (e.g. the visible text), or is included through alternative means, such as additional text hidden with the .sr-only class. This can also be done by using the ariaText prop. ```jsx live Password validation 12+ characters Upper & lower case Number(s) Special character(s) ```
Component Tokens
Note: Click on the token row to copy the token to your clipboard. ```jsx render ``` --- id: badge category: Data Display title: Badge description: Provides a small descriptor for UI elements. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=8892-42895 subDirectory: Badge/v1 --- ```jsx render ``` ```jsx import { Badge } from '@uhg-abyss/web/ui/Badge'; ``` ```jsx sandbox { component: 'Badge', inputs: [ { prop: 'children', type: 'string', }, { prop: 'variant', type: 'select', options: [ { label: 'success', value: 'success' }, { label: 'warning', value: 'warning' }, { label: 'error', value: 'error' }, { label: 'info', value: 'info' }, { label: 'neutral', value: 'neutral' }, ] }, { prop: 'rounded', type: 'boolean', }, { prop: 'outline', type: 'boolean', }, ] } Badge Sandbox ``` ## Variants Use the `variant` property to set the color of the `Badge`. The options are `success`, `warning`, `error`, `info`, and `neutral`. The default is `success`. ```jsx live Success Badge Warning Badge Error Badge Info Badge Neutral Badge Success Badge Warning Badge Error Badge Info Badge Neutral Badge ``` ## Rounded Use the `rounded` property to change the style of the `Badge` from rounded or squared. The default is `false`. ```jsx live Squared Badge Rounded Badge ``` ## Outline Use the `outline` property to turn on the outline of the `Badge`. The default is `false`. ```jsx live Badge Outline Badge ``` ## Icons Use the `icon` property to set the icon of the `Badge`. ```jsx live } variant="success" > Complete } variant="error" > Incomplete ``` ## Width The `Badge` component has a max width of 200px. Excess text will truncate. ```jsx live } variant="info" > Max width of 200 pixels. excess text will truncate. ``` ## Accessibility Use the `ariaText` prop to provide additional information denoted by the color. This will be announced before visible text. For more information visit the accessibility tab. ```jsx live Password validation } ariaText="Passed" variant="success" > 12+ characters } ariaText="Passed" variant="success" > Upper & lower case } ariaText="Missing" variant="error" > Number(s) } ariaText="Missing" variant="error" > Special character(s) ``` ```jsx render Badges are not focusable, visual text elements used to show a status for quick recognition. Avoid using badge for text truncated beyond 200 pixels, because it will not be accessible. #### Decorative Icons In the badge below, since there is sufficient text next to the icon, the icon is considered decorative and and does not need to be exposed to assistive technology. ```jsx live } variant="warning" outline > Warning ``` #### Meaningful Colors Conveying Meaning Via Color Alone: Color must not used as the only means of conveying information, actions, prompting a response, or distinguishing elements. Using color to add meaning only provides a visual indication, which will not be conveyed to users of assistive technologies – such as screen readers. Ensure that information denoted by the color is either obvious from the content itself (e.g. the visible text), or is included through alternative means, such as additional text hidden with the .sr-only class. This can also be done by using the ariaText prop. ```jsx live Password validation } ariaText="Passed" variant="success" > 12+ characters } ariaText="Passed" variant="success" > Upper & lower case } ariaText="Missing" variant="error" > Number(s) } ariaText="Missing" variant="error" > Special character(s) ``` --- id: bar category: Data Visualization title: Bar slug: /web/ui/charts/bar description: A graphical representation of data in a bar-shaped graph. design: https://www.figma.com/design/NnKHAtlU3Q0Xq3RzN9PJe1/Abyss-Data-Visualization?node-id=3-22732 --- Note: JPG and PNG download options are not compatible with Safari. As an alternative, please use the PDF option or take a screenshot. ```jsx import { Charts } from '@uhg-abyss/web/ui/Charts'; ``` ## Bar chart Simple bar chart with `title` and `subtitle` props passed. `xAxisLabel` and `yAxisLabel` are required props for chart. ```jsx live () => { const labels = [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', ]; const data = { labels, datasets: [ { label: 'Dataset 1', data: [65, 59, 80, 81, 56, 55, 40], borderColor: '$primaryDvz1', backgroundColor: '$primaryDvz1', }, ], }; return ( ); }; ``` ## Border radius Bar chart example showing different border radius by passing `borderRadius` property to each dataset. ```jsx live () => { const labels = [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', ]; const data = { labels, datasets: [ { label: 'Fully Rounded', data: [-30, -7, -31, 26, -69, -93, -7], borderColor: '$primaryDvz1', backgroundColor: '$primaryDvz3', borderWidth: 2, borderRadius: Number.MAX_VALUE, borderSkipped: false, }, { label: 'Small Radius', data: [-66, -3, -65, 67, -91, -80, 1], borderColor: '$secondaryDvz1', backgroundColor: Charts.pattern.draw('diagonal', '$secondaryDvz1'), borderWidth: 2, borderRadius: 5, borderSkipped: false, }, ], }; return ( ); }; ``` ## Floating bar chart Using [number, number][] as the type for data to define the beginning and end value for each bar. This is instead of having every bar start at 0. ```jsx live () => { const labels = [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', ]; const data = { labels, datasets: [ { label: 'Dataset 1', data: labels.map(() => { return [Math.random().toFixed(3), Math.random().toFixed(3)]; }), backgroundColor: '$primaryDvz1', }, { label: 'Dataset 2', data: labels.map(() => { return [Math.random().toFixed(3), Math.random().toFixed(3)]; }), backgroundColor: Charts.pattern.draw('dot', '$secondaryDvz1'), }, ], }; return ( ); }; ``` ## Horizontal bar chart Pass `indexAxis` property as `y` to chart options to show chart horizontal. Configuration for the options can be found in the Chart Js docs. ```jsx live () => { const labels = [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', ]; const data = { labels, datasets: [ { label: 'Dataset 1', data: [-32, -61, 57, 89, 59, 6, 75], backgroundColor: '$primaryDvz1', }, { label: 'Dataset 2', data: [-66, -67, -7, 28, -99, -91, 10], backgroundColor: Charts.pattern.draw('line-vertical', '$secondaryDvz1'), }, ], }; return ( ); }; ``` ## Stacked bar chart Pass `stacked` property as `true` in scales for both x and y axises. ```jsx live () => { const labels = [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', ]; const data = { labels, datasets: [ { label: 'Dataset 1', data: [-21, 89, -54, 31, 1, -98, -72], backgroundColor: '$primaryDvz1', }, { label: 'Dataset 2', data: [-88, -55, -66, 86, -58, -85, -6], backgroundColor: Charts.pattern.draw('square', '$secondaryDvz1'), }, { label: 'Dataset 3', data: [-41, -61, 97, 62, 71, 67, -79], backgroundColor: Charts.pattern.draw('cross', '$purpleDvz1'), }, ], }; return ( ); }; ``` ## Stacked bar with groups Pass `stacked` property as `true` in scales for both x and y axises and pass `stack` property to each dataset to group the stacks. ```jsx live () => { const labels = [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', ]; const data = { labels, datasets: [ { label: 'Dataset 1', data: [-21, 89, -54, 31, 1, -98, -72], backgroundColor: '$primaryDvz1', stack: 'Stack 0', }, { label: 'Dataset 2', data: [-88, -55, -66, 86, -58, -85, -6], backgroundColor: '$secondaryDvz1', stack: 'Stack 0', }, { label: 'Dataset 3', data: [-41, -61, 97, 62, 71, 67, -79], backgroundColor: '$purpleDvz1', stack: 'Stack 1', }, ], }; return ( ); }; ``` ## Zoom Use `enableZoom` prop to toggle zooming of chart. The default value is `false`. Configuration for the zoom options can be found in the Zoom Options docs. ```jsx live () => { const labels = [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', ]; const data = { labels, datasets: [ { label: 'Dataset', data: [65, 59, 80, 81, 56, 55, 40], borderColor: '$sapphireDvz1', backgroundColor: '$sapphireDvz1', }, ], }; return (

); }; ``` ## Data structure Data in the datasets can be different structures and can be found in the Data Structures docs. ```jsx live () => { const data = { datasets: [ { label: 'Dataset', data: [ { x: '2016-12-25', y: 20 }, { x: '2016-12-26', y: 10 }, { x: '2016-12-27', y: 25 }, { x: '2016-12-28', y: 30 }, { x: '2016-12-29', y: 50 }, ], borderColor: '$primaryDvz1', backgroundColor: '$primaryDvz1', }, ], }; return (

); }; ``` ## Options Use `options` prop to customize the chart level and dataset level. Configuration for the options can be found in the Options docs. ```jsx live () => { const labels = [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', ]; const data = { labels, datasets: [ { label: 'Dataset 1', data: [65, 59, 80, 81, 56, 55, 40], borderColor: '$primaryDvz1', backgroundColor: '$primaryDvz1', hoverBorderWidth: 2, hoverBorderColor: 'black', }, { label: 'Dataset 2', data: [22, 65, 75, 85, 34, 23, 54], borderColor: '$secondaryDvz1', backgroundColor: Charts.pattern.draw('diagonal', '$secondaryDvz1'), }, ], }; return (

); }; ``` ## Chart description Use `chartDescription` prop to describe the chart and will be shown in chart description accordion below the view data table accordion. The default value of `chartDescription` is `null`. Whether displayed or not, the chart description accordion, including its content, are announced as the “long description” for the chart. ```jsx live () => { const labels = [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', ]; const data = { labels, datasets: [ { label: 'Optum', data: [65, 59, 80, 81, 56, 55, 40], borderColor: '$primaryDvz1', backgroundColor: '$primaryDvz1', }, { label: 'Uhg', data: [22, 65, 75, 85, 34, 23, 54], borderColor: '$secondaryDvz1', backgroundColor: Charts.pattern.draw('diagonal', '$secondaryDvz1'), }, ], }; return (

); }; ``` ## Chart type Use `chartType` prop to describe the type of Bar chart. The default value is `Bar Chart`. ```jsx live () => { const labels = [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', ]; const data = { labels, datasets: [ { label: 'Dataset 1', data: labels.map(() => { return [Math.random().toFixed(3), Math.random().toFixed(3)]; }), backgroundColor: '$primaryDvz1', }, { label: 'Dataset 2', data: labels.map(() => { return [Math.random().toFixed(3), Math.random().toFixed(3)]; }), backgroundColor: Charts.pattern.draw('diagonal', '$secondaryDvz1'), }, ], }; return ( ); }; ``` ## Pattern bar chart Use `Charts.pattern` prop in dataset to make patterns in the bar chart which helps viewers with vision deficiencies. Refer Patternomaly library to generate patterns to fill datasets. ```jsx live () => { const labels = [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', ]; const data = { labels, datasets: [ { label: 'Dataset 1', data: [65, 59, 80, 81, 56, 55, 40], backgroundColor: Charts.pattern.draw('circle', '$secondaryDvz1'), }, ], }; return ( ); }; ``` ## Title offset Use `titleOffset` prop to change the heading level of graph title in a page. The default value is `1`. You can use titleOffset={1|2|3|4|5}. ```jsx live () => { const labels = [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', ]; const data = { labels, datasets: [ { label: 'Dataset', data: [65, 59, 80, 81, 56, 55, 40], borderColor: '$primaryDvz1', backgroundColor: '$primaryDvz1', }, ], }; return (

); }; ``` ## Hiding dropdowns Use the `hideDataTable` prop to remove the "View Data Table" accordion dropdown below the chart. Use the `hideDownloadDropdown` prop to remove the download options dropdown in the upper right corner of the chart. The default setting for both options is `false`. ```jsx live () => { const labels = [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', ]; const data = { labels, datasets: [ { label: 'Dataset 1', data: [65, 59, 80, 81, 56, 55, 40], borderColor: '$primaryDvz1', backgroundColor: '$primaryDvz1', }, ], }; return ( ); }; ``` ## Showing dropdowns Use the `openDataTable` prop to expand the "View Data Table" accordion dropdown below the chart by default. The default is `false`. Setting to `true` expands the accordion by default, while setting it to `'always'` prevents the accordion from being collapsible, and is thus always open. ```jsx live () => { const labels = [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', ]; const data = { labels, datasets: [ { label: 'Dataset 1', data: [65, 59, 80, 81, 56, 55, 40], borderColor: '$primaryDvz1', backgroundColor: '$primaryDvz1', }, ], }; return ( ); }; ``` ```jsx render ``` ```jsx render ```
Chart accessibility requirements
- Text contrast must be 4.5:1 or greater - Single chart bar color contrast must be 3:1 or greater - Multiple dataset must be more than a difference in color - For bar charts: use patterns
Chart “long description”
- Whether displayed or not, the chart description accordion, including its content, are announced as the “long description” for the chart. ```jsx live () => { const labels = [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', ]; const data = { labels, datasets: [ { label: 'Dataset', data: [65, 59, 80, 81, 56, 55, 40], borderColor: '$primaryDvz1', backgroundColor: '$primaryDvz1', }, ], }; return (

); }; ```
Reduced Motion
Animations and transitions that have been changed when a user has `prefers-reduced-motion` set to `reduced` for all Data Visualizations: - No inflation of bars, sections or lines upon initial data rendering - Data point tooltip navigation has animation removed - View Data Table Accordion has transitions removed ```jsx render ```
Known screen reader issues

NVDA and JAWS
Datapoint navigation announce tooltip content twice - The second time includes chart name --- id: box category: Layout title: Box description: Used as a blanket filler to surround just about any component(s) with color or create a box of predefined size. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=20234-77414 --- ```jsx import { Box } from '@uhg-abyss/web/ui/Box'; ``` ```jsx sandbox { component: 'Box', inputs: [ { prop: 'children', type: 'string', }, { prop: 'color', type: 'string', }, { prop: 'padding', type: 'string', }, { prop: 'height', type: 'string', }, { prop: 'width', type: 'string', }, { prop: 'align', type: 'select', options: [ { label: 'start', value: 'start' }, { label: 'center', value: 'center' }, { label: 'end', value: 'end' }, ], }, ] } Box Sandbox ``` ## Padding Use the `padding` property to adjust the ammount of padding around the contents of the `Box`. The padding prop can take in px, rem, em and the Abyss standardized sizes. The default is set to `$md`. ```jsx live Small Padding
Medium Padding - Default
Large Padding ``` ## Color Use the `color` property to set the color of the `Box`. The default is set to `$gray2`. ```jsx live Gray2 - Default White on Primary1 ``` ## Align Use the `align` property to adjust the alignment of children within the `Box`. The default is set to `start`. ```jsx live Start - Default
Center
End ``` ## Width Use the `width` property to adjust the width of the `Box`. The default is set to `100%`. ```jsx live Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet ``` ## Height Use the `height` property to adjust the height of the `Box`. The default is set to `100%`. ```jsx live Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet ``` ## Multi component usage Use `Box` surround groups of components and provides customized colored background. ```jsx live ``` ## Containers ```jsx live Check out this text inside a box container inside a card container ``` ```jsx render ``` ```jsx render ``` --- id: breadcrumbs-v2 category: Navigation title: V2Breadcrumbs description: Used to separate nodes and assist navigation. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=3-23123 subDirectory: Breadcrumbs/v2 sourceIsTS: true --- ```jsx render ``` ```jsx import { V2Breadcrumbs } from '@uhg-abyss/web/ui/Breadcrumbs'; ``` ## Usage Integrate V2Breadcrumbs with [Router](/web/ui/router) by using [Links](/web/ui/link-v2) and Router routes. The V2Breadcrumbs component displays breadcrumbs based on the URL of the current location. Breadcrumbs are used for navigation through multi-level pages. The example below simluates this behavior. ```jsx live () => { const Page = ({ title }) => { return (
{title} {title} Page
); }; return ( } /> } /> } /> Click on these links to mimic the use of breadcrumb navigation

Home Page

Getting Started

Breadcrumbs

); }; ``` ## Title The `title` prop accepts either a string or a function. For static titles, use a string. For dynamic titles, provide a function that accepts the router URL parameters and returns a string. To use URL parameters, utilize React Router's dynamic path segments syntax in the `path` prop of the `Router.Route` and the `href` prop of the breadcrumb. Note: The use of dynamic titles using dynamic path segments requires React Router v6. As such, the example below is not a live example, as our docs site is using v5. ```jsx () => { return ( { return `Component: ${component || 'None'}`; }, href: '/web/ui/:component', }, ]} /> } /> } /> ); }; ``` ## Variant Use the `variant` prop to change the styling of the V2Breadcrumbs. The possible options are `'default'`, and `'alt'`. The default is set to `'default'`. ```jsx live () => { return ( ); }; ``` ## Comparator The `comparator` prop takes in a custom callback function to directly handle the determination of which breadcrumbs are displayed. This function must match the following interface: ```ts comparator?: (href: string, location: Location) => boolean; ``` `href` is the href of the breadcrumb to compare and `location` is the current location object. If no function is specified, the default comparison is between the breadcrumb item href and the current location pathname. ```jsx live () => { const Page = ({ title }) => { return (
{title} {title} Page
); }; const customComparator = (href, location) => { console.log('breadcrumb item href', href); console.log('current location object', location); return href.includes(location.hash) && href.includes(location.pathname); }; return ( } /> } /> } /> Click on these links to mimic the use of breadcrumb navigation

Home Page

Getting Started

Breadcrumbs

); }; ``` ## Mobile width On screens less than 744px wide, the V2Breadcrumbs will only display the previous page title. Resize the window to see the change! ```jsx live () => { return ( ); }; ``` ## onClick Use the `onClick` prop to provide a function that is called when a breadcrumb is clicked. The function receives two arguments: the event and the data of the clicked breadcrumb. ```jsx live () => { return ( { // These two functions are only here for demonstration purposes to prevent the page from navigating e.stopPropagation(); e.preventDefault(); console.log({ e, data }); }} /> ); }; ``` ```jsx render ``` ```jsx render ``` A breadcrumb trail consists of a list of links to the parent pages of the current page in hierarchical order. It helps users find their place within a website or web application. Breadcrumbs are often placed horizontally before a page's main content. Useful links to learn more about the WAI-ARIA design pattern for breadcrumbs: Breadcrumb WAI-ARIA example | ARIA Current. Adheres to the Breadcrumb WAI-ARIA design pattern. ```jsx live () => { return ( ); }; ```
Component Tokens
Note: Click on the token row to copy the token to your clipboard. ```jsx render ``` --- id: breadcrumbs category: Navigation title: Breadcrumbs description: Used to separate nodes and assist navigation. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=0-999 subDirectory: Breadcrumbs/v1 --- ```jsx render ``` ```jsx import { Breadcrumbs } from '@uhg-abyss/web/ui/Breadcrumbs'; ``` ## Usage Integrate Breadcrumbs with Router by using Links and Router Routes. The breadcrumbs will know what breadcrumb items to display based on the URL of the current location. Breadcrumbs are used for navigation through multi-level pages. Clicking through the links below updates breadcrumbs using router. ```jsx live () => { const Page = ({ title }) => { return (
{title} {title} Page
); }; return ( } /> } /> } /> Click on these links to mimic the use of breadcrumb navigation{' '}

Home Page

Getting Started

Breadcrumbs

); }; ``` ## Title The `title` prop accepts either a string or a function. For static titles, use a string. For dynamic titles, provide a function that accepts the router URL parameters and returns a string. To use URL parameters, utilize React Router's dynamic path segments syntax in the `path` prop of the `Router.Route` and the `href` prop of the breadcrumb. Note: The use of dynamic titles using dynamic path segments requires React Router v6. As such, the example below is not a live example, as our docs site is using v5. ```jsx () => { return ( { return `Component: ${component || 'None'}`; }, href: '/web/ui/:component', }, ]} /> } /> } /> ); }; ``` ## Comparator The `comparator` prop takes in a custom callback function to directly handle the determination of what breadcrumbs are displayed. This function is called as part of a `findIndex()` loop through the breadcrumb items and includes two arguments, the breadcrumb item href and current location object. This function must return a value of `true` or `false`. Note: if this prop is not utilized the default comparison is between the breadcrumb item href and the current location pathname. ```jsx live () => { const Page = ({ title }) => { return (
{title} {title} Page
); }; const customComparator = (href, location) => { console.log('breadcrumb item href', href); console.log('current location object', location); return href.includes(location.hash) && href.includes(location.pathname); }; return ( } /> } /> } /> Click on these links to mimic the use of breadcrumb navigation{' '}

Home Page

Getting Started

Breadcrumbs

); }; ``` ## Size Use the `size` prop to change the overall size of the breadcrumb. ```jsx live () => { return ( ); }; ``` ## Space Use the `space` prop to add space between the nodes and divider. ```jsx live ``` ## Leading icon Use the `leadingIcon` prop to add an icon proceeding your breadcrumbs. `leadingIcon` can either be a string from the Material Icon list, or a React component. ```jsx live } items={[ { title: 'Home', href: '/' }, { title: 'Getting Started', href: '/web/developers/overview/' }, { title: 'Breadcrumbs', href: '/web/ui/Breadcrumbs/' }, ]} /> ``` ## Dark mode Use the `isDarkMode` prop to change the color scheme of breadcrumbs. ```jsx live ``` ## onClick Use the `onClick` prop to provide a function that is called when a breadcrumb is clicked. The function receives two arguments: the event and the data of the clicked breadcrumb. ```jsx live () => { return ( { // These two functions are only here for demonstration purposes to prevent the page from navigating e.stopPropagation(); e.preventDefault(); console.log({ e, data }); }} /> ); }; ``` ## Divider Use the `divider` prop to change the divider elements between the breadcrumbs. The recommended usage is for inserting icons. ```jsx live } items={[ { title: 'Home', href: '/' }, { title: 'Getting Started', href: '/web/developers/overview/' }, { title: 'Breadcrumbs', href: '/web/ui/Breadcrumbs/' }, ]} /> ``` ```jsx render ``` ```jsx render ``` A breadcrumb trail consists of a list of links to the parent pages of the current page in hierarchical order. It helps users find their place within a website or web application. Breadcrumbs are often placed horizontally before a page's main content. Useful links to learn more about the WAI-ARIA design pattern for breadcrumbs: Breadcrumb WAI-ARIA example | ARIA Current. Adheres to the Breadcrumb WAI-ARIA design pattern. ```jsx live () => { return ( ); }; ```
Reduced Motion
Animations and transitions that have been changed when a user has `prefers-reduced-motion` set to `reduced`: - Animation of `Link` underline is removed ```jsx render ``` --- id: button-v2 category: Navigation title: V2Button description: Used to trigger an action or event, such as submitting a form, opening a dialog, cancelling an action, or performing a delete operation. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=24-6564 subDirectory: Button/v2 sourceIsTS: true --- ```jsx render ``` ```jsx import { V2Button } from '@uhg-abyss/web/ui/Button'; ``` ```jsx sandbox { component: 'V2Button', inputs: [ { prop: 'color', type: 'select', options: [ { label: 'brand', value: 'brand' }, { label: 'neutral', value: 'neutral' }, { label: 'destructive', value: 'destructive' }, { label: 'inverse', value: 'inverse' }, ], }, { prop: 'variant', type: 'select', options: [ { label: 'filled', value: 'filled' }, { label: 'outline', value: 'outline' }, { label: 'text', value: 'text' }, ], }, { prop: 'size', type: 'select', options: [ { label: '$sm', value: '$sm' }, { label: '$md', value: '$md' }, { label: '$lg', value: '$lg' }, ], }, { prop: 'children', type: 'string', }, { prop: 'isDisabled', type: 'boolean' }, ], } Click Here! ``` ## Size Use the `size` prop to change the size of the button. The default is set to `'$md'`. The size prop can take in the Abyss standardized `'$sm'`, `'$md'`, and `'$lg'`. ```jsx live Small Medium Large Small Medium Large Home Home Home ``` ## Button colors and variants V2Button provides distinct visual styles through separate `color` and `variant` props: - Use the `variant` prop to specify the button style category: `filled`, `outline`, or `text`. - Use the `color` prop to indicate color and purpose: `brand` (primary actions), `neutral` (secondary actions), `destructive` (dangerous actions), or `inverse` (on dark backgrounds). By default, `brand` color and `filled` variant are enabled. ```jsx live Filled Brand Outline Brand Text Brand Filled Neutral Outline Neutral Text Neutral Filled Destructive Outline Destructive Text Destructive Filled Inverse Outline Inverse Text Inverse ``` ## Icons To insert an [IconSymbol](/web/ui/icon-symbol) into the `V2Button`, use the `icon` props. This prop accepts an object of the following type: ```ts { icon: string; position: 'leading' | 'trailing' | 'icon-only'; variant?: 'filled' | 'outlined'; } ``` - `icon`: The name of the icon to display. - `position`: The position of the icon relative to the button text. - `variant`: The variant of the icon. ```jsx live () => { const [isDisabled, setIsDisabled] = useState(true); return ( More Info Continue Previous Next ); }; ``` ### Icon-only Buttons can also be created without any text by providing an icon with position `'icon-only'`. This button can be used with any of the available [variants](#variant). Note: The child text of the button will be visually hidden, but will remain accessible for screen readers. ```jsx live () => { return ( span': { marginTop: '4px', }, }, }} > Home Heart Star Error Edit ); }; ``` ## useForm (recommended) Using the `useForm` hook lets the DOM handle form data. ```jsx live () => { const form = useForm({}); const onSubmit = (data) => { console.log('Submitted'); }; return ( Form Submit ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const onSubmit = () => { console.log('Submitted'); }; return State Submit; }; ``` ## Href If the `href` prop is present, the button will render as an HTML anchor (``) and navigate to the given href when clicked. For an accessible and user-friendly site, it is recommended to use buttons only for executing actions and using [Links](/web/ui/link-v2) instead for navigating to other pages. Additionally, you can set the `openNewWindow` prop to true if you want the link to open in a new window. Note: The `icon` prop will be overridden with a trailing icon indicating the link opens in a new window. ```jsx live Href button ``` ## Disabled Use the `isDisabled` prop to disable the button. Note: It is recommended that screen readers be provided a reason for a button being in a disabled state. For example, if a form submit button is disabled because all fields must have valid inputs before the user is allowed to submit the form, it is helpful to convey this information so the user understands why the button is disabled. As shown in the example below, this can be achieved using the `aria-describedby` attribute and the `VisuallyHidden` component to point to off-screen content that conveys the reason for the disabled state. ```jsx live Submit The submit button is disabled because some form fields have invalid input. Submit The submit button is disabled because some form fields have invalid input. Submit The submit button is disabled because some form fields have invalid input. ``` ## Loading Note: `isDisabled` takes precedence over `isLoading`. If both props are passed, the button will be disabled and the loading spinner will not be shown. A UI concept which merges the loading spinner indicator into the action that invokes it. Primarily intended for use with forms where it gives users immediate feedback upon pressing submit. The use of the `ariaLoadingLabel` prop is highly encouraged for accessibility standards. Be as descriptive as possible when coming up with a description. Common labels are 'Submitting Form', 'Downloading Files', 'Content is loading', etc. When button is passed the `ariaLoadingLabel` prop, it also takes in the `isLoading` attribute to dynamically toggle the Loading Spinner to populate after the text within button. ```jsx Submit ``` With this feature, the accessibility of spinner changes so when being read by a screen reader, the live region of the button will be read. Visit the [V2LoadingSpinner](/web/ui/loading-spinner-v2) documentation to learn more about this accessibility feature. ```jsx live () => { const [isLoading, setIsLoading] = useState(false); const toggleLoading = () => { setIsLoading(!isLoading); }; const onSubmit = () => { console.log('Submit Clicked'); }; return ( Toggle Loading Submit ); }; ``` ```jsx render ``` ```jsx render ``` A button is a widget that enables users to trigger an action or event, such as submitting a form, opening a dialog, canceling an action, or performing a delete operation. A common convention for informing users that a button launches a dialog is to append "…" (ellipsis) to the button label, e.g., "Save as…". Adheres to the Button WAI-ARIA design pattern. ```jsx sandbox { component: 'V2Button', inputs: [ { prop: 'color', type: 'select', options: [ { label: 'brand', value: 'brand' }, { label: 'neutral', value: 'neutral' }, { label: 'destructive', value: 'destructive' }, { label: 'inverse', value: 'inverse' }, ], }, { prop: 'variant', type: 'select', options: [ { label: 'filled', value: 'filled' }, { label: 'outline', value: 'outline' }, { label: 'text', value: 'text' }, ], }, { prop: 'size', type: 'select', options: [ { label: '$sm', value: '$sm' }, { label: '$md', value: '$md' }, { label: '$lg', value: '$lg' }, ], }, { prop: 'children', type: 'string', }, { prop: 'isDisabled', type: 'boolean' }, ], } Click Here! ``` ```jsx render ```
Disabled Accessibility Guidance
It is recommended that a screen reader be provided with a reason for a button being in a disabled state. For example if a form submit button is disabled because all fields must have valid inputs before the user is allowed to submit the form, it can be helpful to convey this information, so the user understands why the button is disabled. Target the disabled button state with the prop `isDisabled`, and use the `aria-describedby` attribute and the `VisuallyHidden` component to point to off-screen content that conveys the reason for the disabled state. ```jsx live Submit The submit button is disabled because form fields have invalid input. ```
Loading State Button
For a loading state, button pulls in the Loading Spinner component and renders a status message to convey the action of loading without taking focus. Loading Spinner is programmed through the `ariaLoadingLabel` property, and has been tested using a screen reader to present a status message to assistive technology without receiving focus. Following the requirements of WAI-ARIA, Loading Spinner follows the requirements 4.1.3: Status Messages. Status messages are defined by WCAG as messages that provide information on the success or results of a user action, but do not change the users context (i.e. take focus). The Toggle Loading button below can be used to toggle the loading state of the Submit button for screen readers. ```jsx live () => { const [isLoading, setIsLoading] = useState(false); const toggleLoading = () => { setIsLoading(!isLoading); }; const onSubmit = () => { console.log('Submit Clicked'); }; return ( Toggle Loading Submit ); }; ```
Triggering Elements
Use the aria-haspopup attribute on buttons or other triggering elements that open content like dialogs, listboxes, trees, menus, grids, etc. Use a corresponding value that indicates what kind of popup will be displayed when the trigger element is activated. In turn, the element that pops up must be of the role indicated. For example use aria-haspop="dialog" on buttons that open modal dialogs. Be sure to include role="dialog" on the containing element of the dialog itself, too. See the docs on 'haspop' for more details:https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup aria-haspopup - Accessibility | MDN The aria-haspopup attribute indicates the availability and type of interactive popup element that can be triggered by the element on which the attribute is set.
Component Tokens
Note: Click on the token row to copy the token to your clipboard. ```jsx render ``` --- id: button category: Navigation title: Button description: Used to trigger an action or event, such as submitting a form, opening a dialog, cancelling an action, or performing a delete operation. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=0-1006 subDirectory: Button/v1 --- ```jsx render ``` ```jsx import { Button } from '@uhg-abyss/web/ui/Button'; ``` ```jsx sandbox { component: 'Button', inputs: [ { prop: 'variant', type: 'select', options: [ { label: 'solid', value: 'solid' }, { label: 'outline', value: 'outline' }, { label: 'tertiary', value: 'tertiary' }, { label: 'destructive', value: 'destructive' }, { label: 'alternate', value: 'alternate' }, { label: 'ghost', value: 'ghost' }, ], }, { prop: 'size', type: 'string', }, { prop: 'children', type: 'string', }, { prop: 'isDisabled', type: 'boolean' }, ], } ``` ## Size Use the `size` prop to change the size of the button. The default is set to `16px` || `$md`. The size prop can take in px, rem, em and the Abyss standardized $sm, $md, and $lg. ```jsx live ``` ## Variant Use the `variant` prop to change the visual style of the Button. You can set the value to `solid`, `outline`,`tertiary`,`destructive`, `alternate`, or `ghost`. The `solid` variant is for the principal call to action on the page. Primary buttons should only appear once per screen (not including the application header, modal dialog, or side panel). The default value is `solid`. Additionally, you can set the prop 'isScreenReadable' to true when using icons with buttons to add an accessible option for all variants. ```jsx live span': { marginTop: '4px', }, }, }} > ``` ## Inserting elements Insert elements into the Button component using the `before` and `after` props. ```jsx live () => { const [isDisabled, setIsDisabled] = useState(true); return ( ); }; ``` ## useForm (recommended) Using the `useForm` hook lets the DOM handle form data. ```jsx live () => { const form = useForm({}); const onSubmit = (data) => { console.log('Submitted'); }; return ( ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const onSubmit = () => { console.log('Submitted'); }; return ; }; ``` ## Href Use the `href` prop to change have the button link away to another page when it is clicked. For an accessible and user friendly site, it is recommended to keep buttons to just actions and using text links for navigating to other pages. Additionally, you can set the `openNewWindow` prop to true if you want the link to open in a new window. Note: The `after` prop will be overridden with an icon indicating the link opens in a new window. ```jsx live ``` ## Loading Pass the `isLoading` prop to show its loading state. ```jsx live ``` ## Disabled guidance It is recommended that a screen reader is provided a reason for a button being in a disabled state. For example if a form submit button is disabled because all fields must have valid inputs before the user is allowed to submit the form, it can be helpful to convey this information so the user understands why the button is disabled. Target the disabled button state with the prop `isDisabled`, and use the `aria-describedby` attribute and the `VisuallyHidden` component to point to off-screen content that conveys the reason for the disabled state. ```jsx live The submit button is disabled because form fields have invalid input. ``` ## Loading A UI concept which merges the loading spinner indicator into the action that invokes it. Primarily intended for use with forms where it gives users immediate feedback upon pressing submit. To use the Loading Spinner, the `ariaLoadingLabel` prop is required. Be as descriptive as possible when coming up with a description. Common labels are 'Submitting Form', 'Downloading Files', 'Content is loading', etc. When button is passed the `ariaLoadingLabel` prop, it also takes in the `isLoading` attribute to dynamically toggle the Loading Spinner to populate after the text within button. ```jsx ```
With this feature, the accessibility of spinner changes so when being read by a screen reader, the live region of the button will be read. Visit the [Loading Spinner](/web/ui/loading-spinner) documentation to learn more about this accessibility feature. ```jsx live () => { const [isLoading, setIsLoading] = useState(false); const toggleLoading = () => { setIsLoading(!isLoading); }; const onSubmit = () => { console.log('Submit Clicked'); }; return ( ); }; ``` ```jsx render ``` ```jsx render ``` A button is a widget that enables users to trigger an action or event, such as submitting a form, opening a dialog, canceling an action, or performing a delete operation. A common convention for informing users that a button launches a dialog is to append "…" (ellipsis) to the button label, e.g., "Save as…". Adheres to the Button WAI-ARIA design pattern. ```jsx sandbox { component: 'Button', inputs: [ { prop: 'variant', type: 'select', options: [ { label: 'solid', value: 'solid' }, { label: 'outline', value: 'outline' }, { label: 'tertiary', value: 'tertiary' }, { label: 'destructive', value: 'destructive' }, { label: 'alternate', value: 'alternate' }, { label: 'ghost', value: 'ghost' }, ], }, { prop: 'size', type: 'string', }, { prop: 'children', type: 'string', }, { prop: 'isDisabled', type: 'boolean' }, ], } ``` ```jsx render ```
Disabled Accessibility Guidance
It is recommended that a screen reader be provided with a reason for a button being in a disabled state. For example if a form submit button is disabled because all fields must have valid inputs before the user is allowed to submit the form, it can be helpful to convey this information, so the user understands why the button is disabled. Target the disabled button state with the prop `isDisabled`, and use the `aria-describedby` attribute and the `VisuallyHidden` component to point to off-screen content that conveys the reason for the disabled state. ```jsx live The submit button is disabled because form fields have invalid input. ```
Loading State Button
For a loading state, button pulls in the Loading Spinner component and renders a status message to convey the action of loading without taking focus. Loading Spinner is programmed through the `ariaLoadingLabel` property, and has been tested using a screen reader to present a status message to assistive technology without receiving focus. Following the requirements of WAI-ARIA, Loading Spinner follows the requirements 4.1.3: Status Messages. Status messages are defined by WCAG as messages that provide information on the success or results of a user action, but do not change the users context (i.e. take focus). The Toggle Loading button below can be used to toggle the loading state of the Submit button for screen readers. ```jsx live () => { const [isLoading, setIsLoading] = useState(false); const toggleLoading = () => { setIsLoading(!isLoading); }; const onSubmit = () => { console.log('Submit Clicked'); }; return ( ); }; ```
Reduced Motion
For users who have `prefers-reduced-motion` set to `reduced`, the animation of the loading symbol is disabled, as well as the ripple effect on click.
Triggering Elements
Use the aria-haspopup attribute on buttons or other triggering elements that open content like dialogs, listboxes, trees, menus, grids, etc. Use a corresponding value that indicates what kind of popup will be displayed when the trigger element is activated. In turn, the element that pops up must be of the role indicated. For example use aria-haspop="dialog" on buttons that open modal dialogs. Be sure to include role="dialog" on the containing element of the dialog itself, too. See the docs on 'haspop' for more details:https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup aria-haspopup - Accessibility | MDN The aria-haspopup attribute indicates the availability and type of interactive popup element that can be triggered by the element on which the attribute is set. --- id: calendar-v2 category: Content title: V2Calendar description: Displays a calendar for users to select a date or date range. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=10742-8733 subDirectory: Calendar sourceIsTS: true --- ```jsx import { useCalendar } from '@uhg-abyss/web/hooks/useCalendar'; import { V2Calendar } from '@uhg-abyss/web/ui/Calendar'; ``` ## Day.js `V2Calendar` relies on the Day.js library to handle date operations. All date inputs to the `V2Calendar` are `Dayjs` objects and the `selectedDates` value returned by the [useCalendar hook](#usecalendar) is also a `Dayjs` object. Abyss includes a [Day.js tool](/web/tools/dayjs), which includes a number of preset Day.js plugins, but you can also install Day.js separately. ```jsx import { dayjs } from '@uhg-abyss/web/tools/dayjs'; ``` ## useCalendar Using the `V2Calendar` requires the `useCalendar` hook to manage the calendar's date selection logic. The `useCalendar` hook accepts two optional parameters: - `selectedDates`: The initial selected date(s) in the calendar. - `isDateRange`: A boolean that indicates whether the calendar is in date range mode. The default is `false`. See [Date range selection](#date-range-selection) for more information. The `useCalendar` hook returns an object with the following properties: - `selectedDates`: The currently selected date(s) in the calendar. - `onDateClick`: A callback function executed when a date is clicked. `V2Calendar` needs both of these values to function correctly, but the returned `selectedDates` can be used in your own logic as well. ```jsx live () => { const { selectedDates, onDateClick } = useCalendar({ selectedDates: dayjs(), }); return ( Selected date: {selectedDates?.format('MMMM D, YYYY') || 'None'} ); }; ``` ## Navigating the calendar The `V2Calendar` header contains buttons to navigate between months and years. The outermost buttons navigate to the same month of the previous/next year, while the inner buttons navigate to the previous/next month. See the [Accessibility tab](?tab=accessibility) for more information on keyboard navigation. ## Initial active month By default, when `V2Calendar` first renders, it will display the real-world current month. Use the `initialActiveMonth` prop to override this and display a different month on initial render. This prop accepts a `Dayjs` object. ```jsx live () => { const { ...calendarProps } = useCalendar({}); return ( ); }; ``` ## Month/year picker Clicking on the month or year displayed at the top of the calendar will open the respective picker, allowing users to quickly change the displayed month or year. ```jsx live () => { const { ...calendarProps } = useCalendar({}); return ; }; ``` ## onMonthChange Use the `onMonthChange` prop to provide a callback function that will be executed whenever the active month changes. The callback function receives the new active month as a `Dayjs` object. ```jsx live () => { const { ...calendarProps } = useCalendar({}); return ( { console.log('Active month changed to:', newMonth.format('YYYY-MM')); }} /> ); }; ``` ## Minimum and maximum dates Use the `minDate` and `maxDate` props to only allow dates within a given range to be selected. Both props accept a `Dayjs` object. These values are inclusive endpoints, meaning that the date(s) provided can be selected. When using `minDate` and/or `maxDate`, the options in the [month or year picker(s)](#monthyear-picker) will be restricted to the range provided. If the range is entirely within a single year, the year picker button will be removed. The same is true for the month picker button with a range within a single month. In the example below, only the dates from one month before today's date to one month after can be selected. ```jsx live () => { const { ...calendarProps } = useCalendar({}); return ( ); }; ``` ## Exclude dates Use the `excludeDate` prop to prevent certain dates from being selected. `excludeDate` accepts a predicate function and checks each date in the current month against it. If the function returns `true`, the matching date will be disabled. In the example below, the `excludeDate` function disables all Sundays and Saturdays. ```jsx live () => { const { ...calendarProps } = useCalendar({}); return ( { return date.day() === 0 || date.day() === 6; }} /> ); }; ``` ## Footer Use the `footer` prop to add a footer to the calendar. The `footer` prop accepts an object of the following type: ```ts interface CalendarFooter { filledButton?: CalendarFooterButton; outlineButton?: CalendarFooterButton; } ``` `CalendarFooterButton` is an object that accepts most props of the [V2Button](/web/ui/button-v2) component, with the exception of `variant`, `size`, and `color`, which are set by the Calendar and cannot be altered. ```jsx live () => { const { ...calendarProps } = useCalendar({}); return ( { console.log('Filled button clicked'); }, }, outlineButton: { children: 'Outline', onClick: () => { console.log('Outline button clicked'); }, }, }} /> ); }; ``` ## Date range selection Set the `isDateRange` parameter of the `useCalendar` hook to `true` to enable date range selection. The `selectedDates` property will return an object with `start` and `end` properties, both of which are `Dayjs` objects. Note: Ranges consisting of a single date are valid. ```jsx live () => { const { selectedDates, onDateClick } = useCalendar({ isDateRange: true, }); const formatSelection = () => { if (!selectedDates) { return 'None'; } if (selectedDates.start && !selectedDates.end) { return `${selectedDates.start.format('MMMM D, YYYY')}`; } return `${selectedDates.start.format( 'MMMM D, YYYY' )} through ${selectedDates.end.format('MMMM D, YYYY')}`; }; return ( {`Selected dates: ${formatSelection()}`} ); }; ``` ## ARIA label Use the `ariaLabel` prop to provide extra screen reader text for the Calendar. ```jsx live () => { const { ...calendarProps } = useCalendar({}); return ; }; ``` ```jsx render ``` ```jsx render ``` ```jsx live () => { const { selectedDates, onDateClick } = useCalendar({ isDateRange: true, }); const formatSelection = () => { if (!selectedDates) { return 'None'; } if (selectedDates.start && !selectedDates.end) { return `${selectedDates.start.format('MMMM D, YYYY')}`; } return `${selectedDates.start.format( 'MMMM D, YYYY' )} through ${selectedDates.end.format('MMMM D, YYYY')}`; }; return ( {`Selected dates: ${formatSelection()}`} { return date.day() === 0 || date.day() === 6; }} onDateClick={onDateClick} footer={{ filledButton: { children: 'Save', onClick: () => { console.log('Filled button clicked'); }, }, outlineButton: { children: 'Cancel', onClick: () => { console.log('Outline button clicked'); }, }, }} /> ); }; ``` ```jsx render ``` ```jsx render ```
Known screen reader issues
- JAWS+Chrome - Works as designed - NVDA+Chrome - Works "mostly" as designed in pass-through (forms) mode - Browse mode does not announce all settings - VO+Safari - Works "partially" as designed - Does not announce: - Grouping (ariaLabel) - Selected dates (single or range)
Component Tokens
Note: Click on the token row to copy the token to your clipboard. ```jsx render ``` --- id: card-v2 category: Content title: V2Card description: A container used to display content related to a single subject. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=24-8026 subDirectory: Card/v2 sourceIsTS: true --- ```jsx render ``` ```jsx import { V2Card } from '@uhg-abyss/web/ui/Card'; ``` ## Usage ```jsx live Here's a base card container Wrapping any component ``` ## V1 replication If teams previously used `Card.Header` and `Card.Section`, a similar look can be created with css overrides. ```jsx live
Here's a Header

Here's a Section
``` ## Custom examples Customize a card by adding components inside the base. Any css can be targeted with 'abyss-card-root'. ```jsx live () => { return (
be-nev-o-lent Adjective
well meaning and kindly. "a benevolent smile"

Learn More
); }; ``` Default padding within the `V2Card` is 16px. This can be overridden, as can the width, etc. ```jsx live () => { return (

Card Title Card Description
{ console.log('Bookmark Section!'); }} > { console.log('Delete Section!'); }} > { console.log('Edit Section!'); }} > ); }; ``` You can use the `FloatingSection` component to create a sticky section. ```jsx live () => { const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, }, { title: 'Open New Tab', onClick: () => { console.log('Open New Tab!'); }, }, { title: 'Save As...', onClick: () => { console.log('Save As...'); }, icon: , }, ]; const form = useForm({}); const onSubmit = (data) => { console.log('data', data); }; const options = [ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]; return (
Fill Out Form } menuItems={menuItems} />
} menuItems={menuItems} /> { console.log('Delete Section!'); }} > ); }; ``` ```jsx render ``` ```jsx render ``` Headings are commonly used within the `V2Card`. The following examples are accessible and have passed Evinced WFA testing. ```jsx live () => { return (

be-nev-o-lent
Adjective
well meaning and kindly. "a benevolent smile"

Learn More
); }; ``` ```jsx live () => { return (

Card Title
Card Description
{ console.log('Bookmark Section!'); }} > { console.log('Delete Section!'); }} > { console.log('Edit Section!'); }} > ); }; ```
Component Tokens
Note: Click on the token row to copy the token to your clipboard. ```jsx render ``` --- id: card category: Content title: Card description: A single or multi-section container used to display content related to a single subject. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=0-1181 subDirectory: Card/v1 --- ```jsx render ``` ```jsx import { Card } from '@uhg-abyss/web/ui/Card'; ``` ```jsx sandbox { component: 'Card', inputs: [ { prop: 'header', type: 'string', }, { prop: 'size', type: 'select', options: [ { label: 'medium', value: 'medium' }, { label: 'small', value: 'small' }, ], }, { prop: 'collapse', type: 'boolean', }, ] } Hello section ``` ## Usage ```jsx live Here's a base card container Wrapping any component ``` ## Section Card can be implemented with any combination of sections. ```jsx live () => { return ( Hello section Hello section ); }; ``` ## Size Use the `size` property to make the card size smaller, The default value is `medium`. ```jsx live () => { return ( A card can be used to display content related to a single subject. The content can consist of multiple elements of varying types and sizes. A card can be used to display content related to a single subject. The content can consist of multiple elements of varying types and sizes. ); }; ``` ## Collapse Use `collapse` prop to make card component collapsible. The default value is `false`. See [CollapseProvider](/web/ui/collapse-provider) for collapsing and expanding multiple cards in unison. The `collapseOnClick` prop will receive a callback whenever the collapse/expand button is clicked, which will return the event and a boolean with the open state. ```jsx live () => { const handleCollapseOnClick = (e, state) => { console.log('click event', e); console.log('open state', state); }; return ( A card can be used to display content related to a single subject. The content can consist of multiple elements of varying types and sizes. ); }; ``` ## Heading level The `headingLevel` prop allows you to set the heading level of the card header. The default value is `3` and renders the heading element as an `
`. ```jsx live Card section content ``` ## Inner card Cards can be nesting within one another to further break down the content. ```jsx live () => { return ( A card can be used to display content related to a single subject. The content can consist of multiple elements of varying types and sizes. A card can be used to display content related to a single subject. The content can consist of multiple elements of varying types and sizes. ); }; ``` ## Sticky You can use the `FloatingSection` component to create a sticky section. Sticky sections will not work when `collapse` is active. ```jsx live () => { const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, }, { title: 'Open New Tab', onClick: () => { console.log('Open New Tab!'); }, }, { title: 'Save As...', onClick: () => { console.log('Save As...'); }, icon: , }, ]; const form = useForm({}); const onSubmit = (data) => { console.log('data', data); }; const options = [ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]; const Header = (
Fill Out Form } menuItems={menuItems} />
); return ( } menuItems={menuItems} /> { console.log('Delete Section!'); }} > ); }; ``` ## Custom examples Customize a card by adding components inside of a section. ```jsx live () => { return ( be-nev-o-lent Adjective
well meaning and kindly. "a benevolent smile" Learn More ); }; ``` ```jsx live () => { return ( Card Title Card Description { console.log('Bookmark Section!'); }} > { console.log('Delete Section!'); }} > { console.log('Edit Section!'); }} > ); }; ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` #### Heading Level Nesting - Card headings must be set manually to correctly nest in page content - They do not support the `` used in the Heading component to do this automatically ```jsx live () => { return ( A card can be used to display content related to a single subject. The content can consist of multiple elements of varying types and sizes. A card can be used to display content related to a single subject. The content can consist of multiple elements of varying types and sizes. ); }; ```
Reduced Motion
For users who have `prefers-reduced-motion` set to `reduced`, when the `Card` is collapsible the animation of the spinning caret and expand/collapse is disabled. --- id: carousel-v2 category: Content title: V2Carousel description: Displays information through a series of slides. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=10472-46992 subDirectory: Carousel/v2 sourceIsTS: true --- ```jsx render ``` ```jsx import { V2Carousel, V2Slide } from '@uhg-abyss/web/ui/Carousel'; ``` ## Usage ```jsx live () => { const content = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam. '; const src = utils.useBaseUrl('img/graphics/1_1.jpg'); const slides = Array.from(Array(4).keys()).map((i) => { return (

Slide {i + 1}
{content}
); }); return ( { console.log('previous slide button clicked'); }} slideIndexOnClick={(index) => { console.log('moved to slide ', index); }} nextSlideOnClick={() => { console.log('next slide button clicked'); }} /> ); }; ``` ## Label Use the `label` prop to provide the title of the carousel. This is required for accessibility and, if no label is provided, will default to `'Carousel'`. By default, `label` is displayed as an `'h2'`. This can be customized with the `headingLevel` prop. ```jsx live () => { const content = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.'; const slides = Array.from(Array(4).keys()).map((i) => { return (

Slide {i + 1}
{content}
); }); return ; }; ``` ## SubText Use the optional prop `subText` to provide more contextual information about the carousel. ```jsx live () => { const content = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.'; const slides = Array.from(Array(4).keys()).map((i) => { return (

Slide {i + 1}
{content}
); }); return ( ); }; ``` ## View all Use the optional `onViewAll` prop to provide a custom method to showcase all the carousel slides. If provided, `onViewAll` will be assigned to the `onClick` event of the "View all" link. The example below demonstrates how to use the `onViewAll` prop to display all the slides using the `Fullscreen` component. ```jsx live () => { const [isOpen, setIsOpen] = useState(false); const onViewAll = () => { console.log('Implement your own custom method'); setIsOpen(true); }; const content = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.'; const slides = Array.from(Array(4).keys()).map((i) => { return (

Slide {i + 1}
{content}
); }); return ( setIsOpen(false)} > {slides} ); }; ``` ## Slides To define a slide of the carousel, wrap your contents in our `V2Slide` sub-component. Use the `slides` prop to pass an array of `V2Slide`s to the carousel. ```jsx live () => { const content = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam. '; const src = utils.useBaseUrl('img/graphics/3_4.jpg'); const slides = Array.from(Array(4).keys()).map((i) => { return (

Slide {i + 1}
{content}
); }); return ; }; ``` ## SlidesPerView Use `slidesPerView` to change how many full slides are viewed at one time. Width of the slides is dynamically adjusted to properly fit the number of `slidesPerView`, while always providing a 32px peek of the next slide. This is to indicate that there are more slides to view. The default is set to `1`. ```jsx live () => { const slides = Array.from(Array(10).keys()).map((i) => { return Card {i + 1}; }); return ( ); }; ``` ## SlidesPerScroll Use `slidesPerScroll` to define how far the carousel should move per scroll. If no value is provided, it will default to match the value of `slidesPerView`. ```jsx live () => { const slides = Array.from(Array(10).keys()).map((i) => { return Card {i + 1}; }); return ( ); }; ``` ## Programatic slide navigation The `V2Carousel` component offers three external ref functions to programatically navigate through it: - `goToPrevSlide` to navigate to the previous slide. - `goToNextSlide` to navigate to the next slide. - `goToSlide` to navigate to a desired slide by passing the slide's index. Note: This function is zero-based index. ```jsx live () => { /** * Typescript Note: * When using the V2Carousel's external ref, you can obtain and implement its types the following way: * import { V2CarouselHandle } from '@uhg-abyss/web/ui/Carousel'; * const carouselRef = useRef(null); */ const carouselRef = useRef(null); const slides = Array.from(Array(10).keys()).map((i) => { return Card {i + 1}; }); return ( carouselRef.current.goToPrevSlide()}> Previous carouselRef.current.goToNextSlide()}> Next carouselRef.current.goToSlide(4)}> Go to slide 5 ); }; ``` ## EmblaOverrides `V2Carousel` uses the library `'embla-carousel-react'`. For further customization, you can use prop `emblaOverrides` to pass in additional options. For more information, look here: https://www.embla-carousel.com/api/options/. Note: We do not support all overrides. Teams who wish to do so may need further individual customization. ```jsx live () => { const slides = Array.from(Array(10).keys()).map((i) => { return Card {i + 1}; }); return ( ); }; ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` A carousel presents a set of items, referred to as slides, by sequentially displaying a subset of one or more slides. Typically, one slide is displayed at a time, and users can activate a next or previous slide control that hides the current slide and "rotates" the next or previous slide into view. In some implementations, rotation automatically starts when the page loads, and it may also automatically stop once all the slides have been displayed. While a slide may contain any type of content, image carousels where each slide contains nothing more than a single image are common. Adheres to the Carousel WAI-ARIA design pattern, in particular, the Carousel with tabs for slide control. ```jsx live () => { const content = 'Carousels allow multiple pieces of content to occupy a single, coveted space. This may placate corporate infighting, but on large or small viewports, people often scroll past carousels. A static hero or integrating content in the UI may be better solutions. But if a carousel is your hero, good navigation and content can help make it effective.'; const src = utils.useBaseUrl('img/graphics/carousel/pillsMd.png'); const slides = Array.from(Array(7).keys()).map((i) => { return (

Topic #{i + 1}

{content}
Source: Nielsen/Norman Group: Carousel Usability: Designing an Effective UI for Websites with Content Overload
); }); return ( ); }; ``` ```jsx render ```
Component Tokens
Note: Click on the token row to copy the token to your clipboard. ```jsx render ``` --- id: carousel category: Content title: Carousel description: Displays information through a series of slides. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=3578-23477 subDirectory: Carousel/v1 --- ```jsx render ``` ```jsx import { Carousel, Slide } from '@uhg-abyss/web/ui/Carousel'; ``` ## Usage ```jsx live () => { const content = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.'; const src = utils.useBaseUrl('img/graphics/carousel/pillsMd.png'); const slides = Array.from(Array(4).keys()).map((i) => { return ( Title {i + 1} {content} Primary ); }); return ( { console.log('previous slide button clicked'); }} slideIndexOnClick={(index) => { console.log('moved to slide ', index); }} nextSlideOnClick={() => { console.log('next slide button clicked'); }} /> ); }; ``` ## No loop Use the `noLoop` property to set whether the slides should loop to the start. The default is set to `false`. This also disables looping for arrow key navigation. ```jsx live () => { const content = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.'; const src = utils.useBaseUrl('img/graphics/carousel/pillsMd.png'); const slides = Array.from(Array(4).keys()).map((i) => { return ( Title {i + 1} {content} Primary ); }); return ; }; ``` ## Programatic slide navigation The `Carousel` component offers three external ref functions to programatically navigate through it: - `goToPrevSlide` to navigate to the previous slide. - `goToNextSlide` to navigate to the next slide. - `goToSlide` to navigate to a desired slide by passing the slide's index. Note: This function is zero-based index. ```jsx live () => { const content = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.'; const src = utils.useBaseUrl('img/graphics/carousel/pillsMd.png'); /** * Typescript Note: * When using the Carousel's external ref, you can obtain and implement its types the following way: * import { CarouselHandle } from '@uhg-abyss/web/ui/Carousel'; * const carouselRef = useRef(null); / const carouselRef = useRef(null); const slides = Array.from(Array(10).keys()).map((i) => { return ( Title {i + 1} {content} Primary ); }); return ( <> ); }; ``` ## Autoplay Use the `autoplay` property to initialize the carousel's autoplay. The slides will cycle at a consistent pace until paused. The default is set to `false`. ```jsx live () => { const content = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.'; const src = utils.useBaseUrl('img/graphics/carousel/pillsMd.png'); const slides = Array.from(Array(4).keys()).map((i) => { return ( Title {i + 1} {content} Primary ); }); return ; }; ``` ### Autoplay delay Use the `autoplayDelay` property to set the delay between slide transitions when `autoplay` is on. The default is set to `3000` ms. For accessibility purposes the minimum value allowed is 3 seconds. ```jsx live () => { const content = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.'; const src = utils.useBaseUrl('img/graphics/carousel/pillsMd.png'); const slides = Array.from(Array(4).keys()).map((i) => { return ( Title {i + 1} {content} Primary ); }); return ; }; ``` ## SlidesPerView Use the `slidesPerView` property to change how many slides are viewed at one time. The default is set to `1`. ```jsx live () => { const content = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam.'; const slides = Array.from(Array(6).keys()).map((i) => { return ( Title {i + 1} {content} Primary ); }); return ; }; ``` ## Compact Use the `compact` property to make the carousel smaller. The default value is `false`. ```jsx live () => { const content = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam.'; const slides = Array.from(Array(2).keys()).map((i) => { return ( Title {i + 1} {content} Primary ); }); return ; }; ``` ## Color variants Use the `variant` property to set the color variant of the carousel. The options are `default`, `white`, `primary`, and `secondary`. The default value is `default`. ```jsx live () => { const content = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore.'; const variants = ['default', 'white', 'primary', 'secondary']; const slides = variants.map((variant) => { return Array.from(Array(2).keys()).map((i) => { return ( Title {i + 1} {content} Primary ); }); }); return ( ); }; ``` ## Heading level You can set the heading level of the title by using the `headingLevel` prop. The default value is `h3`. ```jsx live () => { const content = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.'; const src = utils.useBaseUrl('img/graphics/carousel/pillsMd.png'); const slides = Array.from(Array(4).keys()).map((i) => { return ( Title {i + 1} {content} Primary ); }); return ; }; ``` ## Rounded Use the `rounded` prop to change the style of navigation buttons. ```jsx live () => { const content = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.'; const src = utils.useBaseUrl('img/graphics/carousel/pillsMd.png'); const slides = Array.from(Array(4).keys()).map((i) => { return ( Title {i + 1} {content} Primary ); }); return ; }; ``` ## Minimal Use the `minimal` prop to display the navigation buttons as dots. ```jsx live () => { const content = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.'; const src = utils.useBaseUrl('img/graphics/carousel/pillsMd.png'); const slides = Array.from(Array(4).keys()).map((i) => { return ( Title {i + 1} {content} Primary ); }); return ; }; ``` ```jsx live () => { const matches = useMediaQuery('(max-width: 880px)'); const slides = Array.from(Array(10).keys()).map((i) => { return ( A card can be used to display content related to a single subject. The content can consist of multiple elements of varying types and sizes. ); }); return ( ); }; ``` ## Slides Use the `slides` prop to set custom slides for the carousel. ```jsx live () => { const data = [ { title: 'Go Paperless!', content: 'Get most commercial claim letters online and stop receiving paper....', link: 'Watch', to: 'https://www.google.com', icon: 'clipboard', }, { title: 'Provider Relief Funding', content: 'As part of the CARES Act, UnitedHealth Group is helping HHS distribute $3 billion in immediate relief funding...', link: 'Get More Information', to: 'https://www.google.com', icon: 'cost', }, ]; const SlideWrapper = styled(Slide, { display: 'flex', flexDirection: 'row', width: '100%', height: 225, overflow: 'hidden', borderWidth: 1, borderStyle: 'solid', borderColor: '$gray4', }); const ImageContent = styled('div', { flex: '0 0 35%', maxWidth: '35%', display: 'block', boxSizing: 'border-box', position: 'relative', backgroundColor: 'white', }); const ImageWrapper = styled('div', { position: 'absolute', top: '50%', left: '50%', transform: 'translate(-50%, -50%)', }); const ContentWrapper = styled('div', { flex: '1 1 0%', display: 'block', boxSizing: 'border-box', padding: 25, borderLeftWidth: 1, borderStyle: 'solid', borderColor: '$gray4', backgroundColor: '$tint2', alignContent: 'flex-start', }); const Title = styled('h3', { paddingBottom: 10, fontSize: 26, lineHeight: '26px', color: '$primary1', fontWeight: 'bold', }); const Content = styled('div', { paddingBottom: 10, paddingRight: 30, fontSize: 15, lineHeight: 1.5, maxHeight: 100, overflow: 'hidden', }); const slides = data.map((item, index) => { return ( {item.title} {item.content} {item.link} ); }); return ; }; ``` ## ARIA label Use the `ariaLabel` prop to provide a decriptive ARIA label for the carousel. ```jsx live () => { const content = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.'; const src = utils.useBaseUrl('img/graphics/carousel/pillsMd.png'); const slides = Array.from(Array(4).keys()).map((i) => { return ( Title {i + 1} {content} Primary ); }); return ( ); }; ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` A carousel presents a set of items, referred to as slides, by sequentially displaying a subset of one or more slides. Typically, one slide is displayed at a time, and users can activate a next or previous slide control that hides the current slide and "rotates" the next or previous slide into view. In some implementations, rotation automatically starts when the page loads, and it may also automatically stop once all the slides have been displayed. While a slide may contain any type of content, image carousels where each slide contains nothing more than a single image are common. Adheres to the Carousel WAI-ARIA design pattern, in particular, the Carousel with tabs for slide control. ```jsx live () => { const content = `Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.`; const src = utils.useBaseUrl('img/graphics/carousel/pillsMd.png'); const slides = Array.from(Array(4).keys()).map((i) => { return ( Title {i + 1} {content} Primary ); }); return ; }; ``` # Autoplay Delay Use the `autoplayDelay` property to set the delay between slide transitions when `autoplay` is on. The default is set to `3000` ms. For accessibility purposes the minimum value allowed is 3 seconds. ```jsx live () => { const content = `Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.`; const src = utils.useBaseUrl('img/graphics/carousel/pillsMd.png'); const slides = Array.from(Array(4).keys()).map((i) => { return ( Title {i + 1} {content} Primary ); }); return ; }; ``` # Autoplay Pausing All motion must pause as soon as a user hovers over the carousel with their pointer OR any part of the carousel receives focus via keyboard/tab or pointer. ```jsx live () => { const content = `Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.`; const src = utils.useBaseUrl('img/graphics/carousel/pillsMd.png'); const slides = Array.from(Array(4).keys()).map((i) => { return ( Title {i + 1} {content} Primary ); }); return ; }; ```
Reduced Motion
Animations and transitions that have been changed when a user has `prefers-reduced-motion` set to `reduced`: - `autoplay` is turned off by default ```jsx render ``` --- id: checkbox-v2 category: Forms title: V2Checkbox description: Used to mark an option as true/checked or false/not checked. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=3386-4417 subDirectory: Checkbox/v2 sourceIsTS: true --- ```jsx render ``` ```jsx import { V2Checkbox } from '@uhg-abyss/web/ui/Checkbox'; ``` ```jsx sandbox { component: 'V2Checkbox', inputs: [ { prop: 'label', type: 'string', }, { prop: 'isDisabled', type: 'boolean', }, ] } () => { const [isChecked, setChecked] = useState(true); return ( setChecked(e.target.checked)} /> ); }; ``` ## States - Default - The default checkbox is unchecked. - Checked - Use the `isChecked` prop to mark a checkbox as checked. - Disabled - Use the `isDisabled` prop to disable a checkbox. A disabled checkbox is unusable and unclickable. - Error Message - Use the `errorMessage` prop to display a custom error message below the checkbox. - Success Message - Use the `successMessage` prop to display a custom success message below the checkbox. - Hidden Label - Use the `hideLabel` prop to hide the label but retain screen reader accessibility. - Indeterminate - Use the `isIndeterminate` prop to set the checkbox as indeterminate, which overrides the `checked` prop. Do note, the `isIndeterminate` prop is part of a tri-state property that is unique to checkbox inputs. The indeterminate state _should only be used_ in conjunction with a set of checkboxes like in [V2CheckboxGroup](/web/ui/checkbox-group-v2/). ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2({ defaultValues: { indeterminate: true, 'indeterminate-disabled': true, disabledchecked: true, }, }); const [isChecked, setChecked] = useState(true); return ( setChecked(e.target.checked)} /> ); }; ``` ## useFormV2 (recommended) Disclaimer: `V2FormProvider` and `useFormV2` are to only be used with V2 form input components. Do NOT intermix the versions of form input components, providers and hooks together. Example case of what NOT to do: Use the `V2FormProvider` with `V2Checkbox` and `SelectInput`. This will cause unexpected behavior and is not supported. In this scenario, stay on the V1 version until all the V2 components you need are available. If you're using form input components for which the V2 versions are already available, you can begin integrating `V2FormProvider` and `useFormV2` as well as the V2 versions of the components into your project. This allows you to benefit from the latest features and improvements of the V2 components without waiting for the full V2 suite to be released. Using the `useFormV2` hook for handling Checkbox lets the DOM handle form data. Note: The default error message when `required` is `true` is minimally acceptable for accessibility. It is highly recommended to customize it to be more specific to the use of the field and form. ```jsx live () => { const form = useFormV2(); const onSubmit = (data) => { console.log('submitted', data); }; return ( Submit ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [isChecked, setChecked] = useState(true); return ( setChecked(e.target.checked)} /> ); }; ``` ## Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip) or a [Popover](/web/ui/popover). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. Note: `helper` is right aligned to the parent container. The gap between `label` and `helper` is defined by `space-between`. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); return ( } model="helper-custom" validators={{ required: true }} /> ); }; ``` ```jsx render ``` ```jsx render ```
Checkbox Types
Adheres to the Checkbox WAI-ARIA design pattern. The component's input wrapper has a `role="radiogroup"` attribute, which is essential for screen readers to identify the group of radio buttons and further allow the usage of `aria-required` and `aria-invalid` inside the component. For more details, please visit the following: Although we've added role="radioGroup" to the checkbox wrapper, it serves the same purpose of allowing the usage of `aria-required` and `aria-invalid` attributes inside the component. - [TPGi's Required Groups](https://www.tpgi.com/everythings-more-complicated-in-groups-required-groups/) - [Marking Support](https://adrianroselli.com/2022/02/support-for-marking-radio-buttons-required-invalid.html) WAI-ARIA supports two types of checkbox widgets:
Dual-State Checkbox
The most common type of checkbox, allows the user to toggle between two choices: checked and not checked. ```jsx live () => { const FormSpacing = styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }); const form = useFormV2({ defaultValues: { standard: false, 'pre-selected': true, indeterminate: true, disabled: false, 'disabled-checked': true, 'disabled-indeterminate': true, 'form-checkbox': false, 'hidden-label': false, }, }); const onSubmit = (data) => { console.log('submitted', data); }; return ( Submit ); }; ``` For more information, see the WAI-ARIA mixed checkbox example.
Component Tokens
Note: Click on the token row to copy the token to your clipboard. ```jsx render ``` --- id: checkbox category: Forms title: Checkbox description: Used to mark an option as true/checked or false/not checked. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=506-11843 subDirectory: Checkbox/v1 --- ```jsx render ``` ```jsx import { Checkbox } from '@uhg-abyss/web/ui/Checkbox'; ``` ```jsx sandbox { component: 'Checkbox', inputs: [ { prop: 'label', type: 'string', }, { prop: 'size', type: 'string', }, { prop: 'isDisabled', type: 'boolean', }, ] } () => { const [isChecked, setChecked] = useState(true); return ( setChecked(e.target.checked)} /> ); }; ``` ## States - Default - The default checkbox is unchecked. - isChecked - Use the `isChecked` prop to mark a checkbox as checked. - Disabled - Use the `isDisabled` prop to disable a checkbox. A disabled checkbox is unusable and un-clickable. - Subtext - Use the `subText` prop to insert helpful text below the checkbox. - Error Message - Use the `errorMessage` prop to display a custom error message below the checkbox. - Hidden Label - Use the `hideLabel` prop to hide the label but retain screen reader accessibility. - Indeterminate - Use the `isIndeterminate` prop to set the checkbox as indeterminate, which overrides the `checked` prop. Do note, the `isIndeterminate` prop is part of a tri-state property that is unique to checkbox inputs. The indeterminate state _should only be used_ in conjunction with a set of checkboxes like in [CheckboxTree](/web/ui/checkbox-tree) or [CheckboxGroup](/web/ui/checkbox-group). ```jsx live () => { const form = useForm({ defaultValues: { indeterminate: true, 'indeterminate-disabled': true, disabledchecked: true, }, }); const [isChecked, setChecked] = useState(true); return ( ); }; ``` ## useForm (recommended) Using the `useForm` hook lets the DOM handle form data. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('submitted', data); }; return ( ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [isChecked, setChecked] = useState(true); return ( setChecked(e.target.checked)} /> ); }; ``` ## Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip) or a [Popover](/web/ui/popover). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live () => { const form = useForm(); return ( } model="helper-custom" validators={{ required: true }} /> ); }; ``` ## Size Use the `size` prop to set the height/width of the checkbox, default is set to `md`. Can use predefined sizes or custom number to set size. ```jsx live () => { const form = useForm(); return ( ); }; ``` ## Descriptors display Use the `descriptorsDisplay` prop to set the orientation of the error message and subtext descriptor content. Available variants include 'column' and 'row'. The default is set to 'row'. Use the [FormProvider](/web/ui/form-provider#descriptors-display) and `descriptorsDisplay` to set the descriptors orientation across an entire form. Note: The errorMessage prop does not work with useForm and is only applicable within our form input components when useState is being utilized. See the [useForm Docs](/web/hooks/use-form#set-error) for example use cases with useForm. ```jsx live () => { const [isChecked, setChecked] = React.useState(false); return ( setChecked(e.target.checked)} label="Descriptors Display" subText="Subtext Message" errorMessage="Error Message" descriptorsDisplay="column" /> ); }; ``` ```jsx render ``` ```jsx render ```
Checkbox Types
Adheres to the Checkbox WAI-ARIA design pattern. WAI-ARIA supports two types of checkbox widgets:
Dual-State Checkbox
The most common type of checkbox, it allows the user to toggle between two choices: checked and not checked. ```jsx live () => { const form = useForm({ defaultValues: { standard: false, 'pre-selected': true, indeterminate: true, disabled: false, 'disabled-checked': true, 'disabled-indeterminate': true, subtext: false, 'form-checkbox': false, 'hidden-label': false, }, }); const onSubmit = (data) => { console.log('submitted', data); }; return ( ); }; ```
Tri-State Checkbox
This type of checkbox supports an additional third state known as "partially checked". One common use of a tri-state checkbox can be found in software installers where a single tri-state checkbox is used to represent and control the state of an entire group of installation options. Each option in the group can be individually turned on or off with a dual-state checkbox: - If all options in the group are checked, the overall state is represented by the tri-state checkbox displaying as checked. - If some options in the group are checked, the overall state is represented with the tri-state checkbox displaying as partially checked. - If no options in the group are checked, the overall state is represented with the tri-state checkbox displaying as not checked. The user can use the tri-state checkbox to change all options in the group with a single action: - Checking the overall checkbox checks all options in the group. - Unchecking the overall checkbox will uncheck all options in the group. In some implementations, the system may remember which options were checked the last time the overall status was partially checked. If this feature is provided, activating the overall checkbox a third time recreates that partially checked state where only some options in the group are checked. Tri-state checkboxes will announce differently on different screen readers: - JAWS: "partially checked" - NVDA: "half-checked" - VoiceOver: "mixed" For tri-state checkboxes, we recommend using the [CheckboxTree](/web/ui/checkbox-tree) component, such as shown below: ```jsx live () => { const form = useForm({ defaultValues: { 'checkbox-form': [], }, }); const onSubmit = (data) => { console.log('submitted', data); }; const nodes = [ { value: '/web', label: 'Web', children: [ { value: '/web/ui', label: 'UI', children: [ { value: '/web/ui/forms', label: 'Forms', children: [ { value: '/web/ui/Checkbox', label: 'Checkbox', }, { value: '/web/ui/CheckboxTree', label: 'CheckboxTree', }, ], }, { value: '/web/ui/layout', label: 'Layout', children: [ { value: '/web/ui/Box', label: 'Box', }, { value: '/web/ui/Divider', label: 'Divider', }, ], }, ], }, ], }, ]; return ( ); }; ``` For more information, see the WAI-ARIA mixed checkbox example. --- id: checkbox-group-v2 category: Forms title: V2CheckboxGroup description: Allows a user to select one or multiple items from a list. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=3386-4418 sourceIsTS: true subDirectory: CheckboxGroup/v2 --- ```jsx render ``` ```jsx import { V2CheckboxGroup } from '@uhg-abyss/web/ui/CheckboxGroup'; ``` ## useFormV2 (recommended) Using the `useFormV2` hook lets the DOM handle form data. Disclaimer: `V2FormProvider` and `useFormV2` are to only be used with V2 form input components. Do NOT intermix the versions of form input components, providers and hooks together. Example case of what NOT to do: Use the `V2FormProvider` with `V2CheckboxGroup` and V1 `Checkbox`. This will cause unexpected behavior and is not supported. In this scenario, stay on the V1 version until all the V2 components you need are available. If you're using form input components for which the V2 versions are already available, you can begin integrating `V2FormProvider` and `useFormV2` as well as the V2 versions of the components into your project. This allows you to benefit from the latest features and improvements of the V2 components without waiting for the full V2 suite to be released. ```jsx live () => { const form = useFormV2({ defaultValues: { 'checkbox-form': ['two'], }, }); const onSubmit = (data) => { console.log('submitted', data); }; return ( Submit ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [value, setValue] = React.useState(['1']); const onSubmit = () => { console.log('submitted', value); }; return ( { setValue(e); }} > Submit ); }; ``` ## V2CheckboxGroup.Column The checkbox group is organized into `V2CheckboxGroup.Column` subcomponents. Each `V2Checkbox` is required to be wrapped in a `V2CheckboxGroup.Column` when using `V2CheckboxGroup`. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', variants: { direction: { row: { flexDirection: 'row', }, }, }, }), [] ); const form = useFormV2({}); return ( ); }; ``` ## V2CheckboxGroup.SelectAll Use the `CheckboxGroup.SelectAll` component to create a checkbox for selecting all options. It must live as a child of `CheckboxGroup.Column`. ```jsx live () => { const form = useFormV2({ defaultValues: { 'checkbox-form': ['two'], }, }); const onSubmit = (data) => { console.log('submitted', data); }; return ( Submit ); }; ``` ```jsx live () => { const [value, setValue] = React.useState(['one']); const onSubmit = () => { console.log('submitted', value); }; return ( { setValue(e); }} > Submit ); }; ``` ## Validation ```jsx render ``` Use the `validators` prop to pass in required or custom validations like minimum selection amount. Note: The default error message when `required` is `true` is minimally acceptable for accessibility. It is highly recommended to customize it to be more specific to the use of the field and form. ```jsx live () => { const form = useFormV2(); const onSubmit = (data) => { console.log('submitted', data); }; return ( (value && value.length >= 2) || 'Select At Least 2 Options', }} > Submit ); }; ``` ## Label Use the `label` prop to add a custom checkbox group label. If you do not want to display any label, use prop `hideLabel`. ```jsx live () => { const form = useFormV2(); const onSubmit = (data) => { console.log('submitted', data); }; return ( Submit ); }; ``` ```jsx live () => { const form = useFormV2(); const onSubmit = (data) => { console.log('submitted', data); }; return ( Submit ); }; ``` ## Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip-v2) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip-v2) or a [Popover](/web/ui/popover-v2). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip-v2#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); const onSubmit = (data) => { console.log('submitted', data); }; return ( } model="helper-custom" validators={{ required: true }} > Submit ); }; ``` ## Disabled Use the `isDisabled` prop to disable the entire group. ```jsx live () => { const form = useFormV2(); return ( ); }; ``` ## Multi-line wrapping The `label` for each checkbox button, has a maximum width of `743px`. After that, the text will wrap. ```jsx live () => { const form = useFormV2(); return ( ); }; ``` ## Subtext Use the `subText` prop to display helpful information related to the input field. The prop can take a string or an object in the form of `{text: string; position: 'above' | 'below'}` which allows you to decide if you want to place the `subText` above or below the input field. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); const onSubmit = (data) => { console.log('submitted', data); }; return ( Submit ); }; ``` ## Error message ```jsx render ``` Use the `errorMessage` prop to insert a custom error message below the checkbox group. Note: The errorMessage prop does not work with useFormV2 and is only applicable within our form input components when useState is being utilized. See the [useFormV2 Docs](/web/hooks/use-form-v2#set-error) for example use cases with useFormV2. ```jsx live () => { const [value, setValue] = React.useState(['one']); const onSubmit = () => { console.log('submitted', value); }; return ( { setValue(e); }} > Submit ); }; ``` ## Success message ```jsx render ``` Use the `successMessage` prop to insert a custom success message below the checkbox group that will display when the form submission is successful. ```jsx live () => { const form = useFormV2({ defaultValues: { 'checkbox-form': ['two'], }, }); const onSubmit = (data) => { console.log('submitted', data); }; return ( Submit ); }; ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx live () => { const form = useFormV2({}); const onSubmit = (data) => { console.log('submitted', data); }; return ( } validators={{ required: true }} > Submit ); }; ``` #### ARIA settings on <fieldset> The V2CheckboxGroup component applies the following ARIA attributes to the <fieldset> element: - aria-labelledby: Added since `` is not immediate child of `
`. As a result, `
` will not be correctly labelled (all screen readers). - aria-required: Used to indicate the group requires at least one checkbox selected, not individual checkboxes. Set to`true` when the `isRequired` prop. - aria-invalid: Used to indicate the group has any invalid checkboxes. It is set to `true` when there are errors in the group. - aria-describedBy: This attribute is used on `
` to associate subText and error messages with the group, rather than (all the) individual checkboxes. The intent is to separate errors for any specific checkbox from those that apply to the group. #### Accepted BrAT Variant Behaviors Depending on screen reader (and browser), the settings applied to `
` are not always announced reliably. - JAWS announces all `
` information correctly by default - NVDA announces all `
` information correctly in forms mode - NVDA does not trigger forms mode by default when entering checkboxes - NVDA Browse mode behavior - Announces `` (group name) - Does not announce required, invalid, subtext and error messages - VoiceOver (Mac) announces group label - Does not reliably announce updates to aria-describedby, so error messages may be left out - Does not announce required (aria-required) or invalid (aria-invalid)
Component Tokens
Note: Click on the token row to copy the token to your clipboard. ```jsx render ``` --- id: checkbox-group category: Forms title: CheckboxGroup description: Allows a user to select one or multiple items from a list. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=3585-23398 subDirectory: CheckboxGroup/v1 --- ```jsx render ``` ```jsx import { CheckboxGroup } from '@uhg-abyss/web/ui/CheckboxGroup'; ``` ## useForm (recommended) Using the `useForm` hook lets the DOM handle form data. ```jsx live () => { const form = useForm({ defaultValues: { 'checkbox-form': ['two'], }, }); const onSubmit = (data) => { console.log('submitted', data); }; return ( ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [value, setValue] = React.useState(['1']); const onSubmit = () => { console.log('submitted', value); }; return ( { setValue(e); }} > ); }; ``` ## Validation Use the `validators` prop to pass in required or custom validations like minimum selection amount. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('submitted', data); }; return ( (value && value.length >= 2) || 'Select At Least 2 Options', }} > ); }; ``` ## Label Use the `label` prop to add a custom checkbox group label. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('submitted', data); }; return ( ); }; ``` ## Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip) or a [Popover](/web/ui/popover). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('submitted', data); }; return ( } model="helper-custom" validators={{ required: true }} > ); }; ``` ## Disabled Use the `isDisabled` prop to disable the entire group. ```jsx live () => { const form = useForm(); return ( ); }; ``` ## Subtext Use the `subText` prop to insert helpful text below the checkbox group. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('submitted', data); }; return ( ); }; ``` ## Error message Use the `errorMessage` prop to insert a custom error message below the checkbox group. Note: The errorMessage prop does not work with useForm and is only applicable within our form input components when useState is being utilized. See the [useForm Docs](/web/hooks/use-form#set-error) for example use cases with useForm. ```jsx live () => { const [value, setValue] = React.useState(['1']); const onSubmit = () => { console.log('submitted', value); }; return ( { setValue(e); }} > ); }; ``` ## Descriptors display Use the `descriptorsDisplay` prop to set the orientation of the error message and subtext descriptor content. Available variants include 'column' and 'row'. The default is set to 'row'. Use the [FormProvider](/web/ui/form-provider#descriptors-display) and `descriptorsDisplay` to set the descriptors orientation across an entire form. ```jsx live () => { const [value, setValue] = React.useState(['1']); return ( { setValue(e); }} label="Descriptors Display" subText="Subtext Message" errorMessage="Error Message" descriptorsDisplay="column" > ); }; ``` ## Size Use the `size` prop to set the height/width of the checkbox. Can use predefined sizes or custom number to set size. ```jsx live () => { const form = useForm({ defaultValues: { 'size-sm': ['one', 'two'], 'size-lg': ['one', 'two'], }, }); return ( ); }; ``` ## Display Use the `display` prop to set the orientation of the checkboxes. Available variants include `'column'` and `'row'`. The default is set to `'column'`. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('submitted', data); }; return ( ); }; ``` ## CheckboxGroup.SelectAll Use the `CheckboxGroup.SelectAll` component to create a checkbox for selecting all options. ```jsx live () => { const form = useForm({ defaultValues: { 'checkbox-form': ['two'], }, }); const onSubmit = (data) => { console.log('submitted', data); }; return ( ); }; ``` ```jsx live () => { const [value, setValue] = React.useState(['1']); const onSubmit = () => { console.log('submitted', value); }; return ( { setValue(e); }} > ); }; ``` ```jsx render ``` ```jsx render ``` #### ARIA settings on <fieldset> The CheckboxGroup component applies the following ARIA attributes to the <fieldset> element: - aria-labelledby: Added since `` is not immediate child of `
`. As a result, `
` will not be correctly labelled (all screen readers). - aria-required: Used to indicate the group requires at least one checkbox selected, not individual checkboxes. Set to`true` when the `isRequired` prop. - aria-invalid: Used to indicate the group has any invalid checkboxes. It is set to `true` when there are errors in the group. - aria-describedBy: This attribute is used on `
` to associate subText and error messages with the group, rather than (all of the) individual checkboxes. The intent is to separate errors for any specific checkbox from those that apply to the group. ```jsx live () => { const form = useForm({}); const onSubmit = (data) => { console.log('submitted', data); }; return ( ); }; ``` #### Accepted BrAT Variant Behaviors Depending on screen reader (and browser) the settings applied to `
` are not always announced reliably. - JAWS announces all `
` information correctly by default - NVDA announces all `
` information correctly in forms mode - NVDA does not trigger forms mode by default when entering checkboxes - NVDA Browse mode behavior - Announces `` (group name) - Does not announce required, invalid, subtext and error messages - VoiceOver (Mac) announces group label - Does not reliably announce updates to aria-describedby so error messages may be left out - Does not announce required (aria-required) or invalid (aria-invalid) --- id: checkbox-tree category: Forms title: CheckboxTree description: Allows a user to select one or multiple items from an expandable/collapsible tree design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=25786-98174 --- Note: Please check Accessibility Tab for known issues with VoiceOver ```jsx import { CheckboxTree } from '@uhg-abyss/web/ui/CheckboxTree'; ``` ```jsx render ``` ```jsx sandbox { component: 'CheckboxTree', inputs: [ { prop: 'label', type: 'string', }, { prop: 'subText', type: 'string', }, { prop: 'id', type: 'string', }, { prop: 'size', type: 'string', }, { prop: 'disabled', type: 'boolean', }, { prop: 'onlyLeafCheckboxes', type: 'boolean', }, { prop: 'showExpandAll', type: 'boolean', }, { prop: 'allExpanded', type: 'boolean', }, ] } () => { const nodes = [ { value: '/app', label: 'app', children: [ { value: '/app/Http', label: 'Http', children: [ { value: '/app/Http/Controllers', label: 'Controllers', children: [ { value: '/app/Http/Controllers/WelcomeController.js', label: 'WelcomeController.js', }, ], }, { value: '/app/Http/routes.js', label: 'routes.js', }, ], }, { value: '/app/Providers', label: 'Providers', children: [ { value: '/app/Providers/EventServiceProvider.js', label: 'EventServiceProvider.js', }, ], }, ], }, { value: '/config', label: 'config', children: [ { value: '/config/app.js', label: 'app.js', }, { value: '/config/database.js', label: 'database.js', }, ], }, { value: '/public', label: 'public', children: [ { value: '/public/assets/', label: 'assets', children: [ { value: '/public/assets/style.css', label: 'style.css', }, ], }, { value: '/public/index.html', label: 'index.html', }, ], }, { value: '/.env', label: '.env', }, { value: '/.gitignore', label: '.gitignore', }, { value: '/README.md', label: 'README.md', }, ]; const [checked, setChecked] = useState([]); return ( setChecked(e)} /> ); }; ``` ## Usage The list of which nodes are currently checked can be managed in two ways, the `useForm` hook and the `useState` hook: ### useForm (recommended) Using the `useForm` hook lets the DOM handle form data. ```jsx live () => { const form = useForm({ defaultValues: { 'checkbox-form': ['/app/Http/Controllers/WelcomeController.js'], }, }); const onSubmit = (data) => { console.log('submitted', data); }; const nodes = [ { value: '/app', label: 'app', children: [ { value: '/app/Http', label: 'Http', children: [ { value: '/app/Http/Controllers', label: 'Controllers', }, { value: '/app/Http/Controllers/WelcomeController.js', label: 'WelcomeController.js', }, ], }, ], }, ]; return ( ); }; ``` ### useState Using the `useState` hook gets values from the component state. ```jsx live () => { const nodes = [ { value: '/app', label: 'app', children: [ { value: '/app/Http', label: 'Http', children: [ { value: '/app/Http/Controllers', label: 'Controllers', }, { value: '/app/Http/Controllers/WelcomeController.js', label: 'WelcomeController.js', }, ], }, ], }, ]; const [checked, setChecked] = useState([ '/app/Http/Controllers/WelcomeController.js', ]); const onSubmit = () => { console.log('Submitted', checked); }; return ( { setChecked(e); }} allExpanded /> ); }; ``` ### Manage other props with useState Note that whether you use `useForm` or `useState` to manage the list of checked nodes, you can use `useState` to modify the other props. For example: ```jsx live () => { const form = useForm({ defaultValues: { 'checkbox-form': ['/app/Http/Controllers/WelcomeController.js'], }, }); const onSubmit = (data) => { console.log('submitted', data); }; const initialNodes = [ { value: '/app', label: 'app', children: [ { value: '/app/Http', label: 'Http', children: [ { value: '/app/Http/Controllers', label: 'Controllers', }, { value: '/app/Http/Controllers/WelcomeController.js', label: 'WelcomeController.js', }, ], }, ], }, ]; const [nodes, setNodes] = useState(initialNodes); const [disabled, setDisabled] = useState(false); return ( ); }; ``` ## Nodes The CheckboxTree is made up of nodes, which are specified by passing a list of the node objects into the `nodes` prop. This property is required. Each node has the following properties: ### Label Use the `label` prop to set what will appear on the tree for this node. This does not need to match the node's `value` property. This property is required. ```jsx live () => { const nodes = [ { label: 'This is the label prop', value: 'This value can be different than the label', }, ]; return ; }; ``` ### Value Use the `value` prop to set a unique identifier for the node. No two nodes in the tree can have the same `value`. This property is required. ```jsx live () => { const nodes = [ { value: 'Readme 1', label: '/README.md', }, { value: 'Readme 2', label: '/README.md', }, ]; return ( ); }; ``` ### Children Use the `children` prop to create an array of child nodes. ```jsx live () => { const nodes = [ { value: '/app', label: 'app', children: [ { value: '/app/Http', label: 'Http', children: [ { value: '/app/Http/Controllers', label: 'Controllers', }, { value: '/app/Http/Controllers/WelcomeController.js', label: 'WelcomeController.js', }, ], }, ], }, ]; return ; }; ``` ### Disabled Use the `disabled` prop to disable a node, preventing it from being checked or clicked on. Its default value is `false`. ```jsx live () => { const nodes = [ { value: '/app', label: 'app', children: [ { value: '/app/Http', label: 'Http', children: [ { value: '/app/Http/Controllers', label: 'Controllers', disabled: true, }, { value: '/app/Http/Controllers/WelcomeController.js', label: 'WelcomeController.js', }, ], }, ], }, ]; return ( ); }; ``` ### Show checkbox Use the `showCheckbox` prop to show or hide a checkbox. Its default value is `true`. ```jsx live () => { const nodes = [ { value: '/app', label: 'app', children: [ { value: '/app/Http', label: 'Http', children: [ { value: '/app/Http/Controllers', label: 'This node has showCheckbox set to false', showCheckbox: false, }, { value: '/app/Http/Controllers/WelcomeController.js', label: 'This node has showCheckbox as its default (true)', }, ], }, ], }, ]; return ( ); }; ``` ### Title Use the `title` prop to a custom title attribute for the node. ```jsx live () => { const nodes = [ { value: '/app', label: 'Custom title prop', title: 'This is the title prop', }, ]; return ; }; ``` ## Checked Use the `checked` prop to specify which nodes are checked. If you are using `useForm` to manage checked nodes, you do not need to pass a value for this property; if you are using `useState` for checked nodes, make sure to update your `checked` prop when nodes are checked (using the `onCheck` prop), or else the tree will not update properly. ```jsx live () => { const nodes = [ { value: '/app', label: 'app', children: [ { value: '/app/Http', label: 'Http', }, ], }, { value: '/README.md', label: 'README.md', }, ]; const [checked, setChecked] = useState([]); return ( setChecked(e)} /> ); }; ``` ## onCheck Use the `onCheck` function to trigger a custom function when a checkbox is checked. You can use this to update your checked state from useState, or to do something else entirely. ```jsx live () => { const nodes = [ { value: '/app', label: 'app', children: [ { value: '/app/Http', label: 'Http', children: [ { value: '/app/Http/Controllers', label: 'Controllers', children: [ { value: '/app/Http/Controllers/WelcomeController.js', label: 'WelcomeController.js', }, ], }, { value: '/app/Http/routes.js', label: 'routes.js', }, ], }, { value: '/app/Providers', label: 'Providers', children: [ { value: '/app/Providers/EventServiceProvider.js', label: 'EventServiceProvider.js', }, ], }, ], }, { value: '/config', label: 'config', children: [ { value: '/config/app.js', label: 'app.js', }, { value: '/config/database.js', label: 'database.js', }, ], }, { value: '/public', label: 'public', children: [ { value: '/public/assets/', label: 'assets', children: [ { value: '/public/assets/style.css', label: 'style.css', }, ], }, { value: '/public/index.html', label: 'index.html', }, ], }, { value: '/.env', label: '.env', }, { value: '/.gitignore', label: '.gitignore', }, { value: '/README.md', label: 'README.md', }, ]; const [checked, setChecked] = useState([]); return ( { setChecked(e); console.log('A node was just checked. Now the checked nodes are: ', e); }} /> ); }; ``` ## Validation Use the `validators` prop to specify 1) if at least one option is required to be checked, and 2) custom validations, specified by a callback function that is passed in the selected nodes. ```jsx live () => { const form = useForm({ defaultValues: { 'checkbox-form': ['/README.md'], }, }); const onSubmit = (data) => { console.log('submitted', data); }; const nodes = [ { value: '/.env', label: '.env', }, { value: '/.gitignore', label: '.gitignore', }, { value: '/README.md', label: 'README.md', }, ]; return ( (value && value.length >= 2) || 'Select At Least 2 Options', }} /> ); }; ``` ## Label Use the `label` prop to add a display label that will appear above the tree. ```jsx live () => { const nodes = [ { value: '/README.md', label: '/README.md', }, ]; return ; }; ``` ## Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip) or a [Popover](/web/ui/popover). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live () => { const form = useForm({ defaultValues: { 'helper-tooltip': [], 'helper-popover': [], 'helper-custom': [], }, }); const onSubmit = (data) => { console.log('submitted', data); }; const nodes = [ { value: '/.env', label: '.env', }, { value: '/.gitignore', label: '.gitignore', }, { value: '/README.md', label: 'README.md', }, ]; return ( } nodes={nodes} model="helper-custom" validators={{ required: true }} /> ); }; ``` ## Subtext Use the `subText` prop to insert helpful text below the label. ```jsx live () => { const nodes = [ { value: '/app', label: 'app', }, ]; return ( ); }; ``` ## Descriptors display Use the `descriptorsDisplay` prop to set the orientation of the error message and subtext descriptor content. Available variants include 'column' and 'row'. The default is set to 'row'. Use the [FormProvider](/web/ui/form-provider#descriptors-display) and `descriptorsDisplay` to set the descriptors orientation across an entire form. Note: The errorMessage prop does not work with useForm and is only applicable within our form input components when useState is being utilized. See the [useForm Docs](/web/hooks/use-form#set-error) for example use cases with useForm. ```jsx live () => { const nodes = [ { value: '/app', label: 'app', }, ]; return ( ); }; ``` ## Size Use the `size` prop to set the height/width of the checkboxes. The default is set to `md`. Can use predefined sizes or a custom number to set size. ```jsx live () => { const nodes = [ { value: '/app', label: 'app', children: [ { value: '/app/Http', label: 'Http', children: [ { value: '/app/Http/Controllers', label: 'Controllers', }, { value: '/app/Http/Controllers/WelcomeController.js', label: 'WelcomeController.js', }, ], }, ], }, ]; const [checked, setChecked] = useState([]); return ( ); }; ``` ```jsx live () => { const nodes = [ { value: '/app', label: 'app', children: [ { value: '/app/Http', label: 'Http', children: [ { value: '/app/Http/Controllers', label: 'Controllers', }, { value: '/app/Http/Controllers/WelcomeController.js', label: 'WelcomeController.js', }, ], }, ], }, ]; return ( ); }; ``` ```jsx live () => { const nodes = [ { value: '/app', label: 'app', children: [ { value: '/app/Http', label: 'Http', children: [ { value: '/app/Http/Controllers', label: 'Controllers', }, { value: '/app/Http/Controllers/WelcomeController.js', label: 'WelcomeController.js', }, ], }, ], }, ]; const [checked, setChecked] = useState([]); return ( ); }; ``` ## Disabled Use `disabled` prop to disable all nodes. The default value is `false`. ```jsx live () => { const nodes = [ { value: '/app', label: 'app', children: [ { value: '/app/Http', label: 'Http', children: [ { value: '/app/Http/Controllers', label: 'Controllers', }, { value: '/app/Http/Controllers/WelcomeController.js', label: 'WelcomeController.js', }, ], }, ], }, ]; return ( ); }; ``` ## No cascade Use the `noCascade` prop to set whether a parent node cascades its check state to its children. ```jsx live () => { const nodes = [ { value: '/app', label: 'Click me to see that the check is not cascaded below', children: [ { value: '/app/Http', label: 'Http', children: [ { value: '/app/Http/Controllers', label: 'Controllers', children: [ { value: '/app/Http/Controllers/WelcomeController.js', label: 'WelcomeController.js', }, ], }, { value: '/app/Http/routes.js', label: 'routes.js', }, ], }, { value: '/app/Providers', label: 'Providers', children: [ { value: '/app/Providers/EventServiceProvider.js', label: 'EventServiceProvider.js', }, ], }, ], }, ]; return ( ); }; ``` ```jsx live () => { const nodes = [ { value: '/app', label: 'Click me to see that the check is cascaded below', children: [ { value: '/app/Http', label: 'Http', children: [ { value: '/app/Http/Controllers', label: 'Controllers', children: [ { value: '/app/Http/Controllers/WelcomeController.js', label: 'WelcomeController.js', }, ], }, { value: '/app/Http/routes.js', label: 'routes.js', }, ], }, { value: '/app/Providers', label: 'Providers', children: [ { value: '/app/Providers/EventServiceProvider.js', label: 'EventServiceProvider.js', }, ], }, ], }, ]; return ( ); }; ``` ## showExpandAll Use the `showExpandAll` prop to show two buttons for expanding and collapsing all nodes. The default value is `false`. ```jsx live () => { const nodes = [ { value: '/app', label: 'app', children: [ { value: '/app/Http', label: 'Http', children: [ { value: '/app/Http/Controllers', label: 'Controllers', children: [ { value: '/app/Http/Controllers/WelcomeController.js', label: 'WelcomeController.js', }, ], }, { value: '/app/Http/routes.js', label: 'routes.js', }, ], }, { value: '/app/Providers', label: 'Providers', children: [ { value: '/app/Providers/EventServiceProvider.js', label: 'EventServiceProvider.js', }, ], }, ], }, { value: '/config', label: 'config', children: [ { value: '/config/app.js', label: 'app.js', }, { value: '/config/database.js', label: 'database.js', }, ], }, { value: '/public', label: 'public', children: [ { value: '/public/assets/', label: 'assets', children: [ { value: '/public/assets/style.css', label: 'style.css', }, ], }, { value: '/public/index.html', label: 'index.html', }, ], }, { value: '/.env', label: '.env', }, { value: '/.gitignore', label: '.gitignore', }, { value: '/README.md', label: 'README.md', }, ]; return ( ); }; ``` ## Only leaf checkboxes Use the `onlyLeafCheckboxes` prop to alter the tree such that checkboxes only show for leaf nodes. The default value is `false`. ```jsx live () => { const nodes = [ { value: '/app', label: 'app', children: [ { value: '/app/Http', label: 'Http', children: [ { value: '/app/Http/Controllers', label: 'Controllers', children: [ { value: '/app/Http/Controllers/WelcomeController.js', label: 'WelcomeController.js', }, ], }, { value: '/app/Http/routes.js', label: 'routes.js', }, ], }, { value: '/app/Providers', label: 'Providers', children: [ { value: '/app/Providers/EventServiceProvider.js', label: 'EventServiceProvider.js', }, ], }, ], }, { value: '/config', label: 'config', children: [ { value: '/config/app.js', label: 'app.js', }, { value: '/config/database.js', label: 'database.js', }, ], }, { value: '/public', label: 'public', children: [ { value: '/public/assets/', label: 'assets', children: [ { value: '/public/assets/style.css', label: 'style.css', }, ], }, { value: '/public/index.html', label: 'index.html', }, ], }, { value: '/.env', label: '.env', }, { value: '/.gitignore', label: '.gitignore', }, { value: '/README.md', label: 'README.md', }, ]; const [checked, setChecked] = useState([]); return ( ); }; ``` ## Check model Use the `checkModel` prop to specify which checked nodes should be stored in the `checked` array. The possible values are: - `'leaf'`: Only leaf nodes will be stored in the array - `'all'`: All checked nodes will be stored in the array The default value is `'leaf'`. Note: When using `'all'`, indeterminate checkboxes—parent nodes whose children are not all checked—are not added to the `checked` array. ```jsx live () => { const nodes = [ { value: '/app', label: 'app - Click me to see that only leaf nodes are printed below', children: [ { value: '/app/Http', label: 'Http', children: [ { value: '/app/Http/Controllers', label: 'Controllers', }, { value: '/app/Http/Controllers/WelcomeController.js', label: 'WelcomeController.js', }, ], }, ], }, ]; const [checked, setChecked] = useState([]); return ( setChecked(checked)} allExpanded /> Checked nodes: {checked.join(', ')} ); }; ``` ```jsx live () => { const nodes = [ { value: '/app', label: 'app - Click me to see that all nodes are printed below', children: [ { value: '/app/Http', label: 'Http', children: [ { value: '/app/Http/Controllers', label: 'Controllers', }, { value: '/app/Http/Controllers/WelcomeController.js', label: 'WelcomeController.js', }, ], }, ], }, ]; const [checked, setChecked] = useState([]); return ( setChecked(checked)} checkModel="all" allExpanded /> Checked nodes: {checked.join(', ')} ); }; ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render CheckBoxTree is a WAI-ARIA Tree View pattern that follows the Navigation Treeview Example and Checkbox Example (Mixed-State)
Known limitations of "mixed" state checkbox announcement
The current implementation of this component does not correctly announce the "mixed" (or "half-checked") status checkbox parents with mixed sub-selections. This is due to the underlying use of `` which overrides aria-checked. This is a common issue with the Abyss Checkbox and should be addressed across all components in a future release.
Known Macintosh limitations
##### Inaccessible using VoiceOver VoiceOver continues to have extremely poor support for basic WAI-ARIA tree view. These support issues are well documented (for example: (Not so) Simple ARIA Tree Views and Screen Readers for WAI-ARIA 1.0) and extend into this component. They include not announcing: - Presence of tree structure, level and current position in level - Collapsed state of checkbox nodes or updates when toggled - Any checkboxes below top level Previous versions of this component were "somewhat more" accessible using VoiceOver. They allowed tabbing through all elements, including separate expansion buttons and checkboxes. But the net result was poor operation for all keyboard users by having to tab through ALL buttons. Since these issues are limitations of VoiceOver it was decided to provide the best solution for most keyboard and screen reader users (BrAT combinations). We hope that Apple will work to correct the many known issues supporting tree views in browsers. ##### VoiceOver keyboard operation using ⌘ With a screen reader (NVDA, JAWS) running, Windows keyboard navigation still works with simple arrow keys. With VoiceOver running, it is necessary to use the ⌘ (Command) key with arrows to perform the same operations. ```jsx live () => { const form = useForm({ defaultValues: { 'checkbox-form': ['/drinks/soft'], }, }); const onSubmit = (data) => { console.log('submitted', data); }; const nodes = [ { value: '/apps', label: 'Appetizers', children: [ { value: '/apps/hot/', label: 'Hot', }, { value: '/apps/cold/', label: 'Cold', }, ], }, { value: '/dinner/', label: 'Dinner entrees', children: [ { value: '/dinner/wiches/', label: 'Sandwiches', children: [ { value: '/dinner/wiches/burgers/', label: 'Burgers', }, { value: '/dinner/wiches/hot/', label: 'Hot sandwiches', }, { value: '/dinner/wiches/cold/', label: 'Cold sandwiches', }, ], }, { value: '/dinner/pizzas/', label: 'Pizzas', children: [ { value: '/dinner/pizzas/thin/', label: 'Thin crust', }, { value: '/dinner/pizzas/deep/', label: 'Deep dish', }, { value: '/dinner/pizzas/stuffed/', label: 'Stuffed', }, ], }, { value: '/dinner/platters/', label: 'Platters', children: [ { value: '/dinner/platters/steak/', label: 'Steak and Prime Rib', }, { value: '/dinner/platters/chicken/', label: 'Chicken', }, { value: '/dinner/platters/vegi/', label: 'Vegetarian', }, ], }, ], }, { value: '/drinks', label: 'Drinks', children: [ { value: '/drinks/alcohol/', label: 'Beer & wine', children: [ { value: '/drinks/alcohol/tapbeers', label: 'Beer (on tap)', }, { value: '/drinks/alcohol/canbeers', label: 'Beer (cans and bottles)', }, { value: '/drinks/wines', label: 'Wine', }, ], }, { value: '/drinks/soft', label: 'Soft drinks', }, ], }, { value: '/desserts', label: 'Desserts', }, { value: '/afterdrinks', label: 'After dinner drinks', }, ]; const [checked, setChecked] = useState([]); return ( { setChecked(e); console.log( 'A node was just checked. Now the checked nodes are: ', e ); }} model="checkbox-form" validators={{ required: true, validate: (value) => (value && value.length >= 2) || 'Select at least 2 pages', }} /> ); }; ``` ```jsx render ``` --- id: chip-v2 category: Data Display title: V2Chip description: Chips are compact elements that represent an action, input, or attribute. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=10607-21568 subDirectory: Chip/v2 sourceIsTS: true --- ```jsx render ``` ```jsx import { V2Chip } from '@uhg-abyss/web/ui/V2Chip'; ``` ## onClose Use the `onClose` function to handle the action when the close button is triggered. ```jsx live { console.log('Close button clicked'); }} text="V2Chip with a close button" /> ``` ## leftAddOn Use the `leftAddOn` prop to add a custom element before the text, such as an [IconSymbol](/web/ui/icon-symbol). ```jsx live { console.log('Close button clicked'); }} text="V2Chip with addon" leftAddOn={ } /> ``` ## maxWidth Chips have a max width of `fit-content` by default. Use the optional `maxWidth` prop to pass a number or a string to set a max width. Exceeding the max width will truncate the content on the chip and will be fully visualized with a `V2Tooltip` on hover. ```jsx live {}} maxWidth={200} text="Hover over this chip. This is a chip with a max width of 200" /> {}} maxWidth="300px" text="This is a chip with a max width of 300px" /> {}} text="This is a chip that is not using a maxWidth prop, thus the default 'fit-content' is applied" /> ``` ## Group Use `V2Chip.Group` to group multiple chips together. Use `title` to give the group of chips a label. `title` is required. ```jsx live {}} text="V2Chip in Group" /> {}} text="V2Chip in Group" /> {}} text="V2Chip in Group" /> ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` Chips are focusable and truncated with an ellipsis (if a `maxWidth` is defined). Once a chip has been removed, it cannot be re-rendered. These are primarily used for Select List Multi and Data Table filter. ## Setting focus onClose When implementing `onClose`, the keyboard focus that was on the close button will be lost. As part of implementing `onClose`, update focus (setFocus) needs to be set to a logical place. This may vary depending on use. In general, keep focus in chip groups unless there are none. Unless provided clear design guidance, set focus `onClose` in this order: - Previous Chip (if there is one) - Next Chip (if there is one) - Previous focusable element ```jsx live {}} maxWidth={200} text="Hover over this chip. This is a chip with a max width of 200" /> {}} maxWidth="300px" text="This is a chip with a max width of 300px" /> {}} text="This is a chip that is not using a maxWidth prop, thus the default 'fit-content' is applied" /> ``` ```jsx render ```
Component Tokens
Note: Click on the token row to copy the token to your clipboard. ```jsx render ``` --- id: chip category: Data Display title: Chip description: Chips are compact elements that represent an action, input, or attribute. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=9430-35024 --- ```jsx render ``` ```jsx import { Chip } from '@uhg-abyss/web/ui/Chip'; ``` ## Icon Use the `icon` prop to pass in a specific Icon component. Find further guidance on material icons in the [Material Icons Tab](/web/ui/icon-material). ```jsx live } text="Chip" onClose={() => {}} /> ``` ## onClose Use the `onClose` function to handle the action when close button is triggered. ```jsx live } onClose={() => {}} text="Chip with a close button" /> ``` ## Group Use `Chip.Group` to group multiple chips together. Use `title` to give the group of chips a label. `title` is required. ```jsx live } onClose={() => {}} text="Chip in Group" /> } onClose={() => {}} text="Chip in Group" /> } onClose={() => {}} text="Chip in Group" /> ``` ## Outline Use the `outline` prop to enable or disable the border around the chip. ```jsx live {}} text="Outlined Chip" outline /> {}} text="Default Chip" /> ``` ## Width Chips have a max width of 200px. Exceeding the max width will truncate the content and can be seen with a popover by clicking on the `Chip`. ```jsx live } onClose={() => {}} text="Lorem ipsum dolor sit amet, consectetur adipiscing elit." /> ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` Chips are focusable, and truncated with an ellipsis at 200px. Once a chip has been removed, it cannot be re-rendered. These are primarily used for Select List Multi, and Data Table filter. #### Decorative Icons In the chip below, since there is sufficient text next to the icon, the icon is considered decorative and and does not need to be exposed to assistive technology. Find further guidance on material icons in the [Material Icons Tab](/web/ui/icon-material). ```jsx live } onClose={() => {}} text="Chip" /> ``` ```jsx render ``` --- id: coachmark-v2 category: Overlay title: V2Coachmark description: A temporary message that guides a user through a new or unfamiliar experience. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=11049-907 sourcePath: ui/Coachmark/Coachmark.tsx sourceIsTS: true --- ```jsx import { V2CoachmarkTour } from '@uhg-abyss/web/ui/Coachmark'; ``` ## Running a tour `V2CoachmarkTour` is a provider component that wraps the content of your page and provides the context for the Coachmarks within the tour. The tour's active state is controlled by the `startTour` prop, which is a boolean. If `startTour` is `true`, the tour will begin. To end the tour, set `startTour` to `false`. Typically, this only needs to occur in the `onSkip` and `onFinish` callbacks. ```jsx live () => { const Text = styled('p', { static: { marginBottom: '0', color: '$web.semantic.color.text.content.secondary', }, dynamic: () => { const typography = useToken('typography')( '$web.semantic.typography.p.md-reg' ); return { typography, }; }, }); const [startTour, setStartTour] = useState(false); const step1Id = useAbyssId(); const step2Id = useAbyssId(); const step3Id = useAbyssId(); return ( { setStartTour(false); }} onFinish={() => { setStartTour(false); }} > { setStartTour(true); }} > Start Tour Step 1 Step 2 Step 3 ); }; ``` ## Global callbacks The `V2CoachmarkTour` provider accepts three callbacks that are triggered at various points in the tour: - `onStart`: Called when the tour starts. - `onSkip`: Called when the user skips the tour by clicking the close button. The 1-indexed current step number is passed as an argument. - `onFinish`: Called when the user finishes the tour. These can be used to provide extra functionality at these points, such as logging or analytics tracking. Note: Each step also has its own callbacks for when the user clicks the "Next" or "Previous" buttons, which can be used to provide extra functionality at those points as well. See the [Callbacks](#callbacks) section below for more details. ```jsx live () => { const Text = styled('p', { static: { marginBottom: '0', color: '$web.semantic.color.text.content.secondary', }, dynamic: () => { const typography = useToken('typography')( '$web.semantic.typography.p.md-reg' ); return { typography, }; }, }); const [startTour, setStartTour] = useState(false); const step1Id = useAbyssId(); const step2Id = useAbyssId(); const step3Id = useAbyssId(); return ( { console.log('Tour started'); }} onSkip={(currentStep) => { console.log(`Tour skipped on step ${currentStep}`); setStartTour(false); }} onFinish={() => { console.log('Tour finished'); setStartTour(false); }} > Open the console to see the callbacks in action! { setStartTour(true); }} > Start Tour Step 1 Step 2 Step 3 ); }; ``` ## Default variant The `variant` prop controls the appearance of all Coachmarks in the tour. The valid values are `'gray'` and `'white'`. The default is `'white'`. Note: Individual steps can [override this default](#variant) by setting their own `variant` prop. ```jsx live () => { const Text = styled('p', { static: { marginBottom: '0', color: '$web.semantic.color.text.content.secondary', }, dynamic: () => { const typography = useToken('typography')( '$web.semantic.typography.p.md-reg' ); return { typography, }; }, }); const [startTour, setStartTour] = useState(false); const step1Id = useAbyssId(); const step2Id = useAbyssId(); const step3Id = useAbyssId(); return ( { setStartTour(false); }} onFinish={() => { setStartTour(false); }} > { setStartTour(true); }} > Start Tour Step 1 Step 2 Step 3 ); }; ``` ## Footer The footer of a Coachmark contains the step count and the "Next" and "Previous" buttons. This footer will always be visible if there are multiple steps in the tour and will be removed if there is only a single step. ```jsx live () => { const Text = styled('p', { static: { marginBottom: '0', color: '$web.semantic.color.text.content.secondary', }, dynamic: () => { const typography = useToken('typography')( '$web.semantic.typography.p.md-reg' ); return { typography, }; }, }); const [startMultiStepTour, setStartMultiStepTour] = useState(false); const [startSingleStepTour, setStartSingleStepTour] = useState(false); const step1Id = useAbyssId(); const step2Id = useAbyssId(); const step3Id = useAbyssId(); return ( { setStartMultiStepTour(false); }} onFinish={() => { setStartMultiStepTour(false); }} > This tour will have a footer since there are multiple steps. { setStartMultiStepTour(true); }} > Start Tour Step 1 Step 2 { setStartSingleStepTour(false); }} onFinish={() => { setStartSingleStepTour(false); }} > This tour will not have a footer since there is only one step. { setStartSingleStepTour(true); }} > Start Tour Step 1 ); }; ``` ## Overlay Use the `overlay` prop to add an overlay with a cutout highlighting the target elements in the tour. The default value is `false`. ```jsx live () => { const Text = styled('p', { static: { marginBottom: '0', color: '$web.semantic.color.text.content.secondary', }, dynamic: () => { const typography = useToken('typography')( '$web.semantic.typography.p.md-reg' ); return { typography, }; }, }); const [startTour, setStartTour] = useState(false); const step1Id = useAbyssId(); const step2Id = useAbyssId(); const step3Id = useAbyssId(); return ( { setStartTour(false); }} onFinish={() => { setStartTour(false); }} > { setStartTour(true); }} > Start Tour Step 1 Step 2 Step 3 ); }; ``` ## Steps Use the `steps` prop to provide an array of steps for the tour. Each step is an object that contains the following required properties: - `target`: A CSS selector that identifies the element to highlight during the tour. - `title`: The title of the Coachmark. - `description`: The description of the Coachmark. These and the other optional properties are described in more detail below. The order of the elements in the `steps` array determines the order in which the Coachmarks will be displayed during the tour, regardless of the order of the elements in the DOM, giving you full control over the flow of the tour. ### Target and content The `target` value is a CSS selector that identifies the element to highlight during the tour. It can be any valid query selector that uniquely identifies an element on the page. If the selector does not match any elements on the page, the Coachmark will not be displayed for that step. Note: The examples on this page use the `useAbyssId` hook to generate unique IDs for the elements. You are free to use any method you'd like to generate the selectors. The `title` and `description` properties are used to set the content of the Coachmark. `description` is always required, but `title` is optional. Use the `extraContent` prop to add any extra content you'd like below the description. ```jsx live () => { const Text = styled('p', { static: { marginBottom: '0', color: '$web.semantic.color.text.content.secondary', }, dynamic: () => { const typography = useToken('typography')( '$web.semantic.typography.p.md-reg' ); return { typography, }; }, }); const ExtraContentWrapper = styled('div', { display: 'flex', alignItems: 'center', }); const [startTour, setStartTour] = useState(false); const step1Id = useAbyssId(); const step2Id = useAbyssId(); const step3Id = useAbyssId(); return ( { console.log('This is extra content'); }} icon={{ icon: 'celebration', position: 'trailing', }} > Extra content ), }, ]} startTour={startTour} onSkip={() => { setStartTour(false); }} onFinish={() => { setStartTour(false); }} > { setStartTour(true); }} > Start Tour Step 1 Step 3 Step 2 ); }; ``` ### Variant The `variant` prop controls the appearance of the Coachmark. The valid values are `'gray'` and `'white'`. The default is `'white'`. Note: The `variant` prop in the step definition overrides the [default variant](#default-variant) set by the `V2CoachmarkTour` provider. ```jsx live () => { const Text = styled('p', { static: { marginBottom: '0', color: '$web.semantic.color.text.content.secondary', }, dynamic: () => { const typography = useToken('typography')( '$web.semantic.typography.p.md-reg' ); return { typography, }; }, }); const [startTour, setStartTour] = useState(false); const whiteId = useAbyssId(); const grayId = useAbyssId(); return ( { setStartTour(false); }} onFinish={() => { setStartTour(false); }} > { setStartTour(true); }} > Start Tour White Gray ); }; ``` ### Position Use the `position` prop to change the position of the Coachmark relative to its target. The valid options are `'top'`, `'right'`, `'bottom'`, and `'left'`. The default value is `'top'`. Note: The Coachmark will automatically reposition itself to stay within the viewport. This may result in the Coachmark not appearing on the side defined by the `position` prop and/or not being center-aligned with the target element. Additionally, the use of `'right'` and `'left'` on mobile screens is highly discouraged; prefer using `'top'` and `'bottom'` instead. The example below shows one method of achieving this. ```jsx live () => { const Text = styled('p', { static: { marginBottom: '0', color: '$web.semantic.color.text.content.secondary', }, dynamic: () => { const typography = useToken('typography')( '$web.semantic.typography.p.md-reg' ); return { typography, }; }, }); const [startTour, setStartTour] = useState(false); const topId = useAbyssId(); const rightId = useAbyssId(); const bottomId = useAbyssId(); const leftId = useAbyssId(); const mobileBreakpoint = useToken('sizes')('$core.size.md'); const isMobile = useMediaQuery(`(max-width: ${mobileBreakpoint})`); return ( { setStartTour(false); }} onFinish={() => { setStartTour(false); }} > { setStartTour(true); }} > Start Tour Top Right Bottom Left ); }; ``` ### Callbacks Use the `onNext` and `onPrevious` props to provide extra functionality when the user navigates through the tour. These callbacks are called when the user clicks the "Next" or "Previous" buttons in the Coachmark, respectively. Note: [Additional callbacks](#global-callbacks) are handled by the `V2CoachmarkTour` provider. ```jsx live () => { const Text = styled('p', { static: { marginBottom: '0', color: '$web.semantic.color.text.content.secondary', }, dynamic: () => { const typography = useToken('typography')( '$web.semantic.typography.p.md-reg' ); return { typography, }; }, }); const [startTour, setStartTour] = useState(false); const step1Id = useAbyssId(); const step2Id = useAbyssId(); const step3Id = useAbyssId(); return ( { console.log('Next clicked on Step 1'); }, }, { target: `#${step2Id}`, title: 'Step 2', description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer vitae molestie risus, ut semper mi.', onPrevious: () => { console.log('Previous clicked on Step 2'); }, onNext: () => { console.log('Next clicked on Step 2'); }, }, { target: `#${step3Id}`, title: 'Step 3', description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer vitae molestie risus, ut semper mi.', onPrevious: () => { console.log('Previous clicked on Step 3'); }, }, ]} startTour={startTour} onStart={() => { console.log('Tour started'); }} onSkip={(currentStep) => { console.log(`Tour skipped on step ${currentStep}`); setStartTour(false); }} onFinish={() => { console.log('Tour finished'); setStartTour(false); }} > Open the console to see the callbacks in action! { setStartTour(true); }} > Start Tour Step 1 Step 2 Step 3 ); }; ``` ## Full example ```jsx live Full Page Layout ``` ```jsx render ``` ```jsx render ```
Implementation
There is no explicit WAI-ARIA design pattern for this component. - Steps are updates to single modal dialog - `aria-labelledby` is set to `
` (the `title` prop) and included off-screen step location - `aria-describedby` is set to contents (the `description` prop) - Step (dialog) announcement is triggered by setting focus to close button to announce: - Heading content - Description Content - Close button - Navigation between steps - Blurs dialog - Updates dialog content - Resets focus on close button - UX design: Keyboard focus operation is not same as [ModalDialog](/web/ui/modal-dialog-v2) - By design, tours do not return keyboard focus to starting point, such as "start tour" button below - Exiting the tour sets keyboard focus on the last item highlighted whether using the close button, finishing the tour, or pressing the Escape key - Includes normally non-focusable content - Example: The large icons below are not in tab order but receive focus on exit ```jsx live () => { const Text = styled('p', { static: { marginBottom: '0', color: '$web.semantic.color.text.content.secondary', }, dynamic: () => { const typography = useToken('typography')( '$web.semantic.typography.p.md-reg' ); return { typography, }; }, }); const [startTour, setStartTour] = useState(false); const topId = useAbyssId(); const rightId = useAbyssId(); const bottomId = useAbyssId(); const leftId = useAbyssId(); const mobileBreakpoint = useToken('sizes')('$core.size.md'); const isMobile = useMediaQuery(`(max-width: ${mobileBreakpoint})`); return ( { setStartTour(false); }} onFinish={() => { setStartTour(false); }} > Abyss feature tour Take our tour to learn about some of our core features. { setStartTour(true); }} > Start Tour ); }; ```
Known screen reader issues
Though dialog implementation is standard, announcement and operation is inconsistent across different screen readers and browsers (BrATs).
Testing as of 7/16/2025
- JAWS + Chrome: Works as designed - NVDA + Chrome: Works "mostly" as designed, with extra announcements - First step announced twice - Second time is full dialog content including footer content - Subsequent steps announce as intended but include trigger element - Example: The above example includes "Start Tour button expanded" - NVDA + Edge: In Forms (pass-through) mode (only) - Works as designed - Non-responsive to keyboard in browser mode - VO + Safari: Functional, but announcement is poor - Keyboard operation is correct but only "Close button" is announced - User must manually explore contents - Works with keyboard but content updates (`aria-labelledby`, `aria-describedby`) never announced - Failed F12 experiments included: Adding `aria-live` to dialog do not address issue
Component Tokens
Note: Click on the token row to copy the token to your clipboard. ```jsx render ``` --- id: code-highlighter category: Data Display title: CodeHighlighter description: Used to highlight segments of code. --- ```jsx import { CodeHighlighter } from '@uhg-abyss/web/ui/CodeHighlighter'; ``` ```jsx sandbox { component: 'CodeHighlighter', inputs: [ { prop: 'code', type: 'string', }, { prop: 'language', type: 'string', }, { prop: 'showLineNumbers', type: 'boolean', }, ] } ``` ## Language Use the `language` prop to set the desired language for highlighting. See the following documentation for the complete list of supported languages and their corresponding values. Default value is set to `jsx` (React JSX). ```jsx live () => { const defaultCodeSnippet = `body { background-color: lightblue; } h1 { color: white; text-align: center; } p { font-family: verdana; font-size: 20px; }`; const [value, setValue] = useState(defaultCodeSnippet); return ( setValue(e.target.value)} css={{ 'abyss-text-input-area-root': { marginBottom: '$md' }, }} /> ); }; ``` ## Show line numbers Use the `showLineNumbers` prop to display line numbers within your highlighted code block. ```jsx live () => { const defaultCodeSnippet = `

Hello World

`; return ( ); }; ``` ```jsx render ``` ```jsx render ``` --- id: collapse-provider category: Providers title: CollapseProvider description: Collapse/expand all collapsible children within the provider. design: https://www.figma.com/file/tk08Md4NBBVUPNHQYthmqp/Abyss-Web?node-id=19283%3A68923&t=JCj9pCNkF0FPfk5f-0 --- ```jsx import { CollapseProvider } from '@uhg-abyss/web/ui/CollapseProvider'; ``` ## Usage Wrap any number of collapsible child components utilizing the [useCollapse](/web/hooks/use-collapse/) hook in the `CollapseProvider` to allow for collapse/expand control of all children. ## CollapseProvider.Button Use `CollapseProvider.Button` within the CollapseProvider to interface directly with the collapse/expand functionality. The collapsed state will be uncontrolled and handled internally by the component. If you'd like to provide a default state to all collapsible child components, utilize the [defaultIsOpen](#defaultisopen) prop detailed below. Use the `expandText` and `collapseText` props to set custom text for the expand and collapse buttons. The default text is "Expand All" and "Collapse All", respectively. ```jsx live () => { return ( This card can collapse and expand independently or with use of CollapseProvider This card can collapse and expand independently or with use of CollapseProvider ); }; ``` ## useCollapseContext (custom button) ```jsx import { useCollapseContext } from '@uhg-abyss/web/hooks/useCollapseContext'; ``` To use a custom button that interfaces with the collapse/expand functionality of the `CollapseProvider` use the `useCollapseContext` hook. This hook provides access to the global collapse state and methods to toggle all collapsible children. ```jsx live () => { const CustomCollapseButton = () => { const collapseContext = useCollapseContext(); console.log('collapseContext', collapseContext); const isOpen = collapseContext.state.globalIsOpen; const buttonText = isOpen ? 'Collapse all' : 'Expand all'; const handleClick = () => { collapseContext.methods.toggleAll({ isOpen: !isOpen }); }; return ( ); }; return ( This card can collapse and expand independently or with use of CollapseProvider This card can collapse and expand independently or with use of CollapseProvider ); }; ``` ## defaultIsOpen Use the `defaultIsOpen` prop to set a default collapse state for all collapsible child components within the CollapseProvider. This should be utilized when using `Collapse.Button`. Default value is `true`. ```jsx live () => { return ( This first card can collapse and expand independently or with use of CollapseProvider This second card can collapse and expand independently or with use of CollapseProvider ); }; ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` --- id: content-editor category: Forms title: ContentEditor description: A simple markdown editor with preview. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=47326-126348 --- ```jsx import { ContentEditor } from '@uhg-abyss/web/ui/ContentEditor'; ``` ```jsx render ``` ## Usage ```jsx live () => { const [value, setValue] = useState(` # Heading level 1 ## Heading level 2 ### Heading level 3 #### Heading level 4 ##### Heading level 5 ###### Heading level 6
bold text italicized text* --- [Example Link](https://www.example.com)`); return ( setValue(e.target.value)} /> ); }; ``` ## useForm (recommended) Using the `useForm` hook gets values from the component state. ```jsx live () => { const form = useForm({ defaultValues: { 'content-editor': 'FormProvider Default Value', }, }); const onSubmit = (data) => { console.log('data', data); }; return ( ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [value, setValue] = useState('State Default Value'); return ( setValue(e.target.value)} /> ); }; ``` ## Rendering abyss components You can render the default set of Abyss components (see below) by simply calling the component. For example, to render the Abyss button component, simply type ``. Default Components: [Button](/web/ui/button) / [Badge](/web/ui/badge) / [Checkbox](/web/ui/checkbox) / [CheckboxGroup](/web/ui/checkbox-group) / [CheckboxTree](/web/ui/checkbox-tree) / [Card](/web/ui/card) / [Chip](/web/ui/chip) / [DateInput](/web/ui/date-input) / [DropdownMenu](/web/ui/dropdown-menu) / [Heading](/web/ui/heading) / [Icon](/web/ui/icon) / [IconSymbol](/web/ui/icon-material) / [Label](/web/ui/label) / [Layout](/web/ui/layout) / [Link](/web/ui/link) / [RadioGroup](/web/ui/radio-group) / [Table](/web/ui/table) / [Text](/web/ui/text) / [TextInput](/web/ui/text-input) / [TextInputArea](/web/ui/text-input-area) / [ToggleSwitch](/web/ui/toggle-switch) ```jsx live () => { const [value, setValue] = useState(`## Abyss Components:

Badge

Small label Medium label Large label`); return ( setValue(e.target.value)} /> ); }; ``` ## Height Use the `height` property to adjust the height of the content editor. ```jsx live () => { const [value, setValue] = useState(''); return ( setValue(e.target.value)} /> ); }; ``` ## Preview only Use the `previewOnly` prop to hide the markdown editor section. The default is `false`. ```jsx live () => { const [value, setValue] = useState(` # Heading level 1 ## Heading level 2 ### Heading level 3 #### Heading level 4 ##### Heading level 5 ###### Heading level 6
bold text italicized text --- [Example Link](https://www.example.com)`); return ( setValue(e.target.value)} previewOnly /> ); }; ``` ## Rich text editor Using the `hasRichTextEditor` prop allows the user access to helpful text editing tools. Content made in the Rich Text Editor will be returned as HTML, which is a valid subset of Markdown. All HTML is markdown, but not all Markdown is HTML. Note: When using this prop, you will not be able to pass default Abyss components. ```jsx live () => { const [value, setValue] = useState('State Default Value'); return ( setValue(e.target.value)} /> ); }; ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` --- id: data-grid category: Data Display title: DataGrid description: Edit a matrix of data with columns, rows, and information that can operate dynamically. design: https://www.figma.com/design/YdMuE47bDFEbNxNLAQeqmL/Grid--Eliana-?node-id=34880-116899 --- ```jsx import { DataGrid } from '@uhg-abyss/web/ui/DataGrid'; ``` ## Overview The data grid features are ideal for displaying and editing a matrix of data within the UI. This component shares similar features to a spreadsheet application such as Excel with similar layout, user experience and available functionality. See the following sections below for further details on available features and implementation. ## Usage (useDataGrid) ```jsx import { useDataGrid } from '@uhg-abyss/web/hooks/useDataGrid'; ``` DataGrid requires usage of the `useDataGrid` hook. All available props as displayed within the API integration tab and shown in the examples below must be passed into `useDataGrid`. The return should then be supplied to the `gridState` prop within the `DataGrid` component. There are also methods available in the return from `useDataGrid` such as [updateData](#update-data), [getData](#get-data), [updateColumns](#update-columns), [updateGrid](#update-grid), etc. ```jsx live-in-view () => { const data = [ ['Cell Text', '01/01/2023', '1', 10, 10.25, 10, 10], ['Cell Text', '02/01/2023', '2', 20, -20, 20, 20], ['Cell Text', '03/01/2023', '3', 30, 30.5, 30.5, 30], ['Cell Text', '04/01/2023', '4', 40, 40.75, 40.75, 40], ['Cell Text', '05/01/2023', '1', 50, 50.05, 50.05, 50], ['Cell Text', '06/01/2023', '2', 60, -60, 60, 60], ]; const today = dayjs().format('MM/DD/YYYY'); const getRowHighlightClass = ({ rowIndex }) => { if (rowIndex === 1) { return 'custom-highlight-row'; } return ''; }; const columns = useMemo( () => [ { placeholder: 'Enter Text', cellClassName: ({ rowIndex }) => { return `custom-indicator ${getRowHighlightClass({ rowIndex })}`; }, }, { type: 'date', defaultValue: today, minWidth: 120, cellClassName: getRowHighlightClass, }, { type: 'select', options: [ { value: '1', label: 'Option 1' }, { value: '2', label: 'Option 2' }, { value: '3', label: 'Option 3' }, { value: '4', label: 'Option 4' }, ], placeholder: 'Pick an option', cellClassName: getRowHighlightClass, }, { type: 'number', placeholder: 'add number here', disabled: ({ rowData, rowIndex }) => { return rowData > 40; }, cellClassName: getRowHighlightClass, }, { type: 'number', numericConfig: { prefix: '$', decimalScale: 2, fixedDecimalScale: true, }, cellClassName: ({ rowData, rowIndex }) => { const customClassNames = [getRowHighlightClass({ rowIndex })]; if (typeof rowData === 'number' && rowData < 0) { customClassNames.push('custom-red-text'); } return customClassNames.join(' '); }, }, { type: 'number', numericConfig: { decimalScale: 2, fixedDecimalScale: true, }, cellClassName: getRowHighlightClass, }, { type: 'number', numericConfig: { suffix: '%', }, cellClassName: getRowHighlightClass, }, ], [] ); const dataGridProps = useDataGrid({ initialData: data, initialColumns: columns, rowResize: true, columnMove: true, rowMove: true, columnSort: true, columnFilter: true, css: { 'abyss-data-grid-row-cell': { '&.custom-indicator': { '&:before': { content: '', position: 'absolute', margin: 'auto', width: 0, borderTop: 'solid 8px $gray5', borderRight: 'solid 8px transparent', }, }, '&.custom-highlight-row': { backgroundColor: '$warning2', }, '&.custom-red-text': { '.abyss-text-input, .abyss-data-grid-cell-display-text': { color: '$error1', fontWeight: '$bold', }, }, }, }, }); return ; }; ``` ## Grid title A title is required for accessibility reasons. Use the `gridTitle` prop to pass in a title that describes the grid. The title is hidden by default. If you'd like the title to be displayed pass in the `showGridTitle` prop. ## Grid read-only Set the `readOnly` prop to `true` on `useDataGrid` to place all data cells within the grid into read-only mode. Read-only cells are not editable, but the cell's data can be copied. If you'd like to manage the read-only configuration at the column level, please see the [Column Read-Only](#disabled--read-only) section below. ```jsx live-in-view () => { const [readOnly, setReadOnly] = useState(true); const { data, columns } = utils.useDocDataGrid(6, 4); const dataGridProps = useDataGrid({ initialData: data, initialColumns: columns, readOnly, }); return ( setReadOnly(e.target.checked)} /> ); }; ``` ## Data Use the `initialData` prop to provide the data to DataGrid on load. This takes in an array of arrays with the values that correspond to the desired row and column. After load, you can use the following data methods: ### Update data To make any updates to the grid data after load, use the `updateData` method that's returned from `useDataGrid`. ```jsx live-in-view () => { const { data } = utils.useDocDataGrid(2, 6); const dataGridProps = useDataGrid({ initialData: data, }); const handleDataOnClick = () => { const { data } = utils.useDocDataGrid(4, 6); dataGridProps.updateData(data); }; return ( ); }; ``` ### Get data To retrieve the current state of the data from the grid, call the `getData` method that's returned from `useDataGrid`. ```jsx live-in-view () => { const [retrievedData, setRetrievedData] = useState([]); const { data } = utils.useDocDataGrid(2, 6); const dataGridProps = useDataGrid({ initialData: data, }); const handleRetrieveOnClick = () => { const data = dataGridProps.getData(); setRetrievedData(data); }; return ( ); }; ``` ## Columns Use the `initialColumns` prop to supply the DataGrid with the column information for your grid. Columns is an array of objects that take in the following properties covered below. After initial load, if you need to change the columns content, please set the [Update Columns](#update-columns) section below. Note: If no column information is provided, all column properties will be set to their respective default values. The number of columns will be determined by the length of the `initialData` provided. If no data is available, it will be set by [startColumns](#start-columnsrows) or default to `5` columns. ### Title Use the `title` prop to provide a custom name to a column header. If no title is provided for a column, the default headers (A, B, C, etc.) will be displayed in alphabetical order. ```jsx live-in-view () => { const { data } = utils.useDocDataGrid(2, 6); const columns = [ { title: 'Col 1' }, { title: 'Col 2' }, {}, {}, { title: 'Col 5' }, { title: 'Col 6' }, ]; const dataGridProps = useDataGrid({ initialData: data, initialColumns: columns, }); return ; }; ``` ### Type All cells of a given column are of the same type and have the same widget. The following columns types are available: #### text (default) ```jsx live-in-view () => { const data = [['Text data goes here']]; const columns = [{ title: 'Text Column', type: 'text' }]; const dataGridProps = useDataGrid({ initialData: data, initialColumns: columns, maxWidth: 250, }); return ; }; ``` #### date Note the below configurations only affect the calendar picker and do not provide validation on the input field. Use the validator prop to handle validation of the input field on blur. Additional Configurations: - Min/Max Date - Use the `minimumDate` and `maximumDate` props to set the min and max dates in the calendar picker. - Excluded Dates - To exclude dates within the calendar picker, use the `excludeDates` prop. Set a function that receives date as an argument and returns true if date should be disabled. - Starting/Ending Year - Use the `startingYear` and `endingYear` props to set the min and max years in the calendar picker. ```jsx live-in-view () => { const data = [['01/01/2023']]; const columns = [{ title: 'Date Column', type: 'date' }]; const dataGridProps = useDataGrid({ initialData: data, initialColumns: columns, maxWidth: 250, }); return ; }; ``` #### select Additional Configurations: - Label/Value Key - Use the `valueKey` and `labelKey` props to change the key that is used to read the labels and values from the options list. - Section Headers - Add description headers to your drop-down option list items. - Custom Render - Used the `customRender` prop to customize the render of each option item. Provides the item object as the first parameter and the item state as the second. - Option List Height - Use the `maxListHeight` prop to set the maximum height of the drop-down menu. The default value is 185px. ```jsx live-in-view () => { const selectOptions = [ { value: '1', label: 'Option 1' }, { value: '2', label: 'Option 2' }, { value: '3', label: 'Option 3' }, { value: '4', label: 'Option 4' }, ]; const data = [['1']]; const columns = [ { title: 'Select Column', type: 'select', options: selectOptions, }, ]; const dataGridProps = useDataGrid({ initialData: data, initialColumns: columns, maxWidth: 250, }); return ; }; ``` #### number Below are examples of the available number configurations. For further configurations please see the following site for additional props that can be passed into the `numericConfig` property. ```jsx live-in-view () => { const data = [[100, 10.25, 100, 10.25]]; const columns = [ { title: 'Number Column', type: 'number' }, { title: 'Decimal Column', type: 'number', numericConfig: { decimalScale: 2, }, }, { title: 'Percent Column', type: 'number', numericConfig: { suffix: '%', isNumericString: false, }, }, { title: 'Currency Column', type: 'number', numericConfig: { prefix: '$', decimalScale: 2, fixedDecimalScale: true, }, }, ]; const dataGridProps = useDataGrid({ initialData: data, initialColumns: columns, }); return ; }; ``` ### Default value Use the `defaultValue` prop to set a default value within each empty cell in the column. To generate an empty grid with no data, please see the [Start Columns/Rows](#start-columnsrows) section. ```jsx live-in-view () => { const columns = [ { title: 'Col 1', defaultValue: 'Column 1 Default Data' }, { title: 'Col 2' }, {}, {}, { title: 'Col 5' }, { title: 'Col 6' }, ]; const dataGridProps = useDataGrid({ initialColumns: columns, startRows: 2, startColumns: 6, }); return ( ); }; ``` ### Column width Column width is dynamically computed using flex settings. To control minimum and maximum width values for a particular column, use the `minWidth` and `maxWidth` props. The default `minWidth` value is `100` and anything below will not be applied. ```jsx live-in-view () => { const { data } = utils.useDocDataGrid(4, 10); const columns = useMemo( () => [ { minWidth: 120, title: 'Min-Width 120' }, { title: 'Min-Width Default 100' }, { minWidth: 140, title: 'Min-Width 140' }, { title: 'Min-Width Default 100' }, { minWidth: 160, title: 'Min-Width 160' }, { title: 'Min-Width Default 100' }, { minWidth: 180, title: 'Min-Width 180' }, { title: 'Min-Width Default 100' }, { title: 'Min-Width Default 100' }, { title: 'Min-Width Default 100' }, ], [] ); const dataGridProps = useDataGrid({ initialData: data, initialColumns: columns, }); return ; }; ``` ### Hide The `hide` prop can be used when you do not want to display all columns of data in the `DataGrid`. ```jsx live-in-view () => { const { data } = utils.useDocDataGrid(4, 7); const columns = useMemo( () => [ { title: 'Col 1' }, { hide: true, title: 'Col 2 Hidden' }, { title: 'Col 3' }, { hide: true, title: 'Col 4 Hidden' }, { title: 'Col 5' }, { hide: true, title: 'Col 6 Hidden' }, { title: 'Col 7' }, ], [] ); const dataGridProps = useDataGrid({ initialData: data, initialColumns: columns, }); return ; }; ``` ### Sort Use the `sort` prop within a column object to designate its sort functionality. If a sort value is applied, either true or false, this will override the global sort configuration. For more information on column sorting please see the [Column Sort](#column-sort) section. ```jsx live-in-view () => { const { data } = utils.useDocDataGrid(6, 4); const columns = useMemo(() => [{ title: 'Is Sortable', sort: true }], []); const dataGridProps = useDataGrid({ initialData: data, initialColumns: columns, }); return ; }; ``` ### Filter Use the `filter` prop within a column object to designate its filter functionality. If a filter value is applied, either true or false, this will override the global filter configuration. For more information on column filtering please see the [Column Filter](#column-filter) section. ```jsx live-in-view () => { const { data } = utils.useDocDataGrid(6, 4); const columns = useMemo(() => [{ title: 'Is Filterable', filter: true }], []); const dataGridProps = useDataGrid({ initialData: data, initialColumns: columns, }); return ; }; ``` ### Update columns To make any updates to the grid columns after load, use the `updateColumns` method that's returned from `useDataGrid`. If you'd like to update both the columns and interior cell data use [updateGrid](#update-grid). ```jsx live-in-view () => { const { data, columns } = utils.useDocDataGrid(2, 6); const dataGridProps = useDataGrid({ initialData: data, initialColumns: columns, }); const handleUpdateColOnClick = () => { const { columns: updatedColumns } = utils.useDocDataGrid(2, 3); dataGridProps.updateColumns(updatedColumns); }; return ( ); }; ``` ### Disabled / read-only The `disabled` prop accepts either a boolean or a function. If a boolean value of `true` is provided, it will disable the entire column. If a function is provided, it receives an object containing `rowIndex` and `rowData` and must return a boolean. Disabled columns are not editable and do not allow copying of cell data. The `readOnly` prop mirrors `disabled` with one exception: read-only cells allow copying of cell data. To apply a read-only state to all data cells within a grid, please see the [Grid Read-Only](#grid-read-only) section above. ```jsx live-in-view () => { const DISABLED_CELL_ROWS = [4, 5]; const READ_ONLY_CELL_ROWS = [1, 2]; const createData = (count, columnCount) => { const data = []; for (let i = 0; i < count; i++) { let row = []; for (let columnIndex = 0; columnIndex < columnCount; columnIndex++) { let cellData = `Col ${columnIndex + 1}/Row ${i + 1}`; if ( columnIndex === 0 || (columnIndex === 2 && DISABLED_CELL_ROWS.includes(i + 1)) ) { cellData = `${cellData} (Disabled)`; } if ( columnIndex === 1 || (columnIndex === 3 && READ_ONLY_CELL_ROWS.includes(i + 1)) ) { cellData = `${cellData} (Read Only)`; } row = [...row, cellData]; } data.push(row); } return data; }; const columns = useMemo(() => { return [ { title: 'Disabled Column', disabled: true }, { title: 'Read Only Column', readOnly: true }, { title: 'Disabled Cells', disabled: ({ rowIndex, rowData }) => { return DISABLED_CELL_ROWS.includes(rowIndex + 1); }, }, { title: 'Read Only Cells', readOnly: ({ rowIndex, rowData }) => { return READ_ONLY_CELL_ROWS.includes(rowIndex + 1); }, }, ]; }, []); const dataGridProps = useDataGrid({ initialData: createData(6, 4), initialColumns: columns, }); return ( ); }; ``` ### Custom component Use the `component` prop within a column object to pass a custom component to render within the cell. See below for the props that will be passed to the component. ```jsx live-in-view () => { const data = [ [true, 'Col 1/Row 1'], [false, 'Col 2/Row 1'], [true, 'Col 1/Row 2'], [false, 'Col 2/Row 2'], ]; const CheckboxCellContainer = styled('div', { display: 'flex', alignItems: 'center', justifyContent: 'center', width: '100%', height: '100%', '.abyss-checkbox-input': { '&:focus': { outline: 'none', }, }, }); const Checkbox = ({ rowData, setRowData, focus, stopEditing, active, columnData, rowIndex, ...props }) => { const inputRef = useRef(null); useEffect(() => { if (focus) { stopEditing({ nextRow: false }); // prevent from entering edit mode and moving to next row } if (active) { setTimeout(() => { inputRef.current?.focus(); // set focus to checkbox input when cell is active }, 10); } }, [active, focus]); return ( { setRowData(e.target.checked); }} tabIndex={-1} ref={inputRef} /> ); }; const columns = useMemo( () => [ { title: 'Custom Component', component: Checkbox, ariaRoleDescription: 'checkbox', pasteValue: ({ rowData, value }) => { return value === 'true'; // ensure pasted value is boolean }, columnData: { label: 'Checkbox Cell', // additional data to be passed to the component }, }, ], [] ); const dataGridProps = useDataGrid({ initialData: data, initialColumns: columns, }); return ; }; ``` #### Custom component props When creating a custom component, the following props are available: | Prop | Type | Description | | --------------- | -------- | ----------------------------------------------- | | `rowData` | any | The data for the current cell | | `setRowData` | function | Function to update the cell data | | `active` | boolean | Whether the cell is currently active (selected) | | `focus` | boolean | Whether the cell is in edit mode | | `stopEditing` | function | Function to exit edit mode | | `setEditing` | function | Function to enter edit mode | | `setActiveCell` | function | Function to set the active cell | | `rowIndex` | number | The index of the current row | | `columnIndex` | number | The index of the current column | | `isDisabled` | boolean | Whether the cell is disabled | | `columnData` | object | Additional column data passed to the component | | `defaultValue` | any | Default value for the cell | ### Other column props - `updateOnChange` When true, cell data will be written on input change. Default is false and recommended for better performance. - `validator` Use to handle validation of the cell. It takes a function that receives two arguments, the newly entered value and previous value (if available), and must return the desired value. The function is called on blur of cell edit and when pasting values to the cell. If updateOnChange is set to true, it will be called on input change. - `cellClassName` Takes either a string with a single class name or a function that receives a single argument as an object with the `rowIndex` and `rowData`. Use to add a custom class to a cell that can be targeted using the `css` prop. - `textAlign` Determines text alignment within a columns cells. Available options are `'left' | 'center' | 'right'`. Default value is `right` for all numeric values and `left` for all others. - `placeholder` Adds a placeholder value to the columns cells. The placeholder value will only be displayed when a cell is active/selected and contains no data. - `disabled` Takes either a boolean or a function. If a boolean is provided, it will disable the entire column. If a function is provided, it receives an object with the `rowIndex` and `rowData` and must return a boolean. Disabled columns will not be editable or allow for copying of cell data. - `readOnly` Takes either a boolean or a function. If a boolean is provided, it will set the entire column as read-only. If a function is provided, it receives an object with the `rowIndex` and `rowData` and must return a boolean. Read-only columns will not be editable but will allow for copying of cell data. - `move` Set whether the column is movable. If a value is applied, either true or false, this will override the global `columnMove` configuration. - `disableContextMenu` Set whether the context menu is disabled for all cells within a column. If a value is applied, either true or false, this will NOT override the global `disableContextMenu` configuration. - `ariaRoleDescription` Use when utilizing a custom component to set the role description for the column. When using a built in column type, the role description is automatically set by the type. ```jsx { updateOnChange: boolean, validator: function, cellClassName: function | string, textAlign: string, placeholder: string, disabled: boolean | function readOnly: boolean | function move: boolean disableContextMenu: boolean ariaRoleDescription: string } ``` ## Layout ### Start columns/rows If no `initialData` is set, the `startColumns` and `startRows` props are used to generate a grid with empty cells. Both default to a value of `5`. ```jsx live-in-view () => { const dataGridProps = useDataGrid({ startRows: 2, startColumns: 6, }); return ( ); }; ``` ### Hide gutter column If `hideGutterColumn` is set to `true`, the left-most numerical gutter column will not be visible. The gutter column is displayed by default. ```jsx live-in-view () => { const dataGridProps = useDataGrid({ startRows: 2, startColumns: 6, hideGutterColumn: true, }); return ; }; ``` ### Grid height/width Use the `maxHeight` and `maxWidth` props to set the maximum height and width of the grid. If no height or width is provided, both will default to a value of `100%`. If the content becomes larger than these values, the grid will become scrollable. ```jsx live-in-view () => { const dataGridProps = useDataGrid({ startRows: 6, startColumns: 6, maxHeight: 200, maxWidth: 500, }); return ( ); }; ``` ### Row height Use the `rowHeight` prop to either pass in an array of row heights or a single number value that will be applied across all rows. If no row height is supplied, it will default to a value of `40px`. The minimum height allowed is `20px`. ```jsx live-in-view () => { const dataGridProps = useDataGrid({ startRows: 4, startColumns: 6, rowHeight: [40, 60, 80, 100], }); return ; }; ``` ### Header row height Use the `headerRowHeight` prop to set the height of the column header row. The default value is `40px`. ```jsx live-in-view () => { const dataGridProps = useDataGrid({ startRows: 2, startColumns: 6, headerRowHeight: 80, }); return ; }; ``` ## Operations ### Update grid To make any updates after load to both the grid columns and the interior cell values, use the `updateGrid` method that's returned from `useDataGrid`. ```jsx live-in-view () => { const { data, columns } = utils.useDocDataGrid(2, 6); const dataGridProps = useDataGrid({ initialData: data, initialColumns: columns, }); const handleColAndDataOnClick = () => { const { columns: updatedColumns } = utils.useDocDataGrid(2, 3); const { data: updatedData } = utils.useDocDataGrid(4, 6); dataGridProps.updateGrid(updatedColumns, updatedData); }; const handleUpdateColOnClick = () => { const { columns: updatedColumns } = utils.useDocDataGrid(2, 3); dataGridProps.updateColumns(updatedColumns); }; const handleDataOnClick = () => { const { data: updatedData } = utils.useDocDataGrid(4, 6); dataGridProps.updateData(updatedData); }; const handleResetOnClick = () => { dataGridProps.updateGrid(columns, data); }; return ( ); }; ``` ### Reorder rows/columns Use the `rowMove` and `columnMove` props to enable the ability to reorder rows and/or columns. A row or column must first be selected in order to drag it to another location on the grid. Once a row/column is selected by clicking on the corresponding row/column header cell, the hand tool will display and the selected row/column can be moved. Currently, only one row/column may be moved at a time. ```jsx live-in-view () => { const { data } = utils.useDocDataGrid(6, 6); const dataGridProps = useDataGrid({ initialData: data, rowMove: true, columnMove: true, }); return ( ); }; ``` ### Column sort Use the `columnSort` prop to globally turn on sort functionality for all columns. When applied the sort arrow indicators will display within the column header cells and sort functionality can be accessed within the [Context Menu](#context-menu). When sorting is active for a column, the corresponding ascending/descending sorting indicator will be highlighted blue. Note that the sort configuration within an individual column will take precedence over this global setting. ```jsx live-in-view () => { const { data } = utils.useDocDataGrid(6, 4); const dataGridProps = useDataGrid({ initialData: data, columnSort: true, }); return ; }; ``` ### Column filter Use the `columnFilter` prop to globally turn on filter functionality for all columns. When applied, the filter indicator will display within the column header cells and filter functionality can be accessed within the [Context Menu](#context-menu). When filtering is active for a column, the corresponding indicator will be highlighted blue. Note that there is a limit of 2 filters per column, and the filter configuration within an individual column will take precedence over this global setting. ```jsx live-in-view () => { const { data } = utils.useDocDataGrid(6, 4); const dataGridProps = useDataGrid({ initialData: data, columnFilter: true, }); return ; }; ``` #### Update filtering To programmatically make filter updates, use the `updateFilter` method that's returned from useDataGrid. See the configuration details below, along with an example of how you can set an initial filter state on load. ```jsx const filters = [ { columnIndex: 1, // The index of the column to apply the filter on value: [ // Limited to 2 filters per column { condition: 'contains', // The condition to filter on filterValue: '10' // The filter value operator: 'and' // The operator if more than one filter is applied. Can be either 'and'/'or'; default is 'and' }, ] }, ... // More filters on other columns ], ``` The `condition` property within `value` must be one of the following strings: - `is-empty` - Empty cell - `not-empty` - Non-empty cell - `equals` - Equal to - `not-equal` - Not equal to - `contains` - Contains - `starts-with` - Starts with - `ends-with` - Ends with - `greater` - Greater than (number type only) - `greater-equal` - Greater than or equal to (number type only) - `less` - Less than (number type only) - `less-equal` - Less than or equal to (number type only) - `before` - Before (date type only) - `after` - After (date type only) - `between` - Between (date type only) ```jsx live-in-view () => { const { data } = utils.useDocDataGrid(6, 4); const dataGridProps = useDataGrid({ initialData: data, columnFilter: true, }); useEffect(() => { const filters = [ { columnIndex: 1, value: [ { condition: 'contains', filterValue: 'Row 2', operator: 'or' }, { condition: 'contains', filterValue: 'Row 4' }, ], }, ]; dataGridProps.updateFilters(filters); }, []); return ; }; ``` ### Resize rows Use the `rowResize` prop to enable the ability to resize rows by dragging the resize handle available on hover of the bottom of each row header cell. ```jsx live-in-view () => { const { data } = utils.useDocDataGrid(6, 4); const dataGridProps = useDataGrid({ initialData: data, rowResize: true, }); return ; }; ``` ### Disable auto fill Use the `disableAutoFill` prop to disable the UI fill handle and the ability to drag and copy cell values across multiple column and row cells. Auto-fill is enabled by default. ```jsx live-in-view () => { const [isDisabled, setIsDisabled] = useState(true); const { data } = utils.useDocDataGrid(6, 4); const dataGridProps = useDataGrid({ initialData: data, disableAutoFill: isDisabled, }); return ( setIsDisabled(e.target.checked)} /> ); }; ``` ### Context menu Use the context menu to access contextual actions such as copying data or deleting/inserting columns or rows. To open the context menu, right-click or press `Shift + F10` for Mac and `Control + Shift + F10` for Windows, while on any cell and the applicable options will be made available. While on a column or row header cell the `Enter` key will open the context menu and simultaneously select the contents for the selected column or row. Here is a list of the currently available options: - Sort Ascending - Sort Descending - Filter - Copy - Cut - Paste - Insert row above - Insert row below - Delete row(s) - Insert column before - Insert column after - Delete column(s) To disable the context menu, use the `disableContextMenu` prop. The menu is enabled by default. ```jsx live-in-view () => { const [isDisabled, setIsDisabled] = useState(false); const { data } = utils.useDocDataGrid(2, 4); const dataGridProps = useDataGrid({ initialData: data, disableContextMenu: isDisabled, }); return ( setIsDisabled(e.target.checked)} /> ); }; ``` ### Insert row/column To programmatically insert new rows or columns, call `insertRow` or `insertColumn` method that's returned from `useDataGrid`. It takes two arguments: the index of the row or column you'd like to insert around and the insert position of either 'before' or 'after'. ```jsx live-in-view () => { const { data } = utils.useDocDataGrid(2, 6); const [type, setType] = useState('row'); const [insertPosition, setInsertPosition] = useState('before'); const [index, setIndex] = useState(0); const typeLabel = type.charAt(0).toUpperCase() + type.slice(1); const dataGridProps = useDataGrid({ initialData: data, }); useEffect(() => { setIndex(0); }, [type]); const options = useMemo(() => { const currentData = dataGridProps.getData(); const columns = dataGridProps.columns; const indexLengths = { row: currentData.length, column: columns.length, }; return new Array(indexLengths[type]).fill({}).map((_, index) => { const typeTitle = type === 'row' ? index + 1 : columns[index].title; return { value: index, label: `${typeLabel} ${typeTitle}` }; }); }, [data, type]); const handleInsertRow = () => { dataGridProps.insertRow(index, insertPosition); }; const handleInsertColumn = () => { dataGridProps.insertColumn(index, insertPosition); }; const insertFunction = { row: handleInsertRow, column: handleInsertColumn, }; return ( setType(e.target.value)} value={type} > setInsertPosition(e.target.value)} value={insertPosition} > ); }; ``` ### Delete rows/columns To programmatically delete rows or columns, call the `deleteRows` or `deleteColumns` method that's returned from `useDataGrid`. It takes two arguments: the starting and then ending row or column for the selection range you'd like to delete. If you'd like to only delete a single row or column, only the starting index is required. ```jsx live-in-view () => { const { data } = utils.useDocDataGrid(2, 6); const [type, setType] = useState('row'); const [startIndex, setStartIndex] = useState('0'); const [endIndex, setEndIndex] = useState('0'); const typeLabel = type.charAt(0).toUpperCase() + type.slice(1); const dataGridProps = useDataGrid({ initialData: data, }); useEffect(() => { setStartIndex('0'); setEndIndex('0'); }, [type]); const options = useMemo(() => { const currentData = dataGridProps.getData(); const columns = dataGridProps.columns; const indexLengths = { row: currentData.length, column: columns.length, }; return new Array(indexLengths[type]).fill({}).map((_, index) => { const typeTitle = type === 'row' ? index + 1 : columns[index].title; return { value: index.toString(), label: `${typeLabel} ${typeTitle}` }; }); }, [data, type]); const handleDeleteRow = () => { dataGridProps.deleteRows(startIndex, endIndex); }; const handleDeleteColumn = () => { dataGridProps.deleteColumns(startIndex, endIndex); }; const insertFunction = { row: handleDeleteRow, column: handleDeleteColumn, }; return ( setType(e.target.value)} value={type} > ); }; ``` ## Events ### onActiveCellChange The `onActiveCellChange` prop take a function that is called each time the active cell is changed and includes the active cell's column index, row index and column id. ```typescript { col: number, // active cell column index row: number, // active cell row index colId: string, } ``` ```jsx live-in-view () => { const { data } = utils.useDocDataGrid(2, 4); const dataGridProps = useDataGrid({ initialData: data, onActiveCellChange: (activeCellData) => { console.log('active cell data', activeCellData); }, }); return ( ); }; ``` ### onSelectionChange The `onSelectionChange` prop take a function that is called each time cell selection is changed and includes the min and max cell data. ```typescript { min: { col: number, row: number, colId: string, }, max: { col: number, row: number, colId: string, } } ``` ```jsx live-in-view () => { const { data } = utils.useDocDataGrid(2, 4); const dataGridProps = useDataGrid({ initialData: data, onSelectionChange: (selectionData) => { console.log('selection data', selectionData); }, }); return ; }; ``` ### onEditEnter / onEditLeave The `onEditEnter` and `onEditLeave` props take a function that is called each time a cell enters or leaves edit mode and includes the current cell's column index, row index and column id. ```typescript { col: number, // active cell column index row: number, // active cell row index colId: string, } ``` ```jsx live-in-view () => { const { data } = utils.useDocDataGrid(2, 4); const dataGridProps = useDataGrid({ initialData: data, onEditEnter: (editCellData) => { console.log('on edit enter cell data', editCellData); }, onEditLeave: (editCellData) => { console.log('on edit leave cell data', editCellData); }, }); return ( ); }; ``` ### onRowCreate The `onRowCreate` prop takes a function that includes the column data as an argument and should return a new row object. It is called each time the user adds a new row. The return object must include the `id` for the columns you'd like to apply new data. This is typically used for adding custom data whenever a new row is added. If not used, an empty row will be generated and any column default data will be applied to the applicable cells. ```jsx live-in-view () => { const { data } = utils.useDocDataGrid(2, 4); const handleRowCreate = (columns) => { const defaultData = columns.reduce((dataObj, { id, title }) => { return { ...dataObj, [id]: `Col ${title} Default Data`, }; }, {}); return defaultData; }; const dataGridProps = useDataGrid({ initialData: data, onRowCreate: handleRowCreate, }); return ; }; ``` ### onColumnCreate The `onColumnCreate` prop takes a function that should return a new column object. It is called each time the user adds a new column. Use this function to return custom column settings. If not utilized, the default [text](#text-default) type column will be created. ```jsx live-in-view () => { const { data } = utils.useDocDataGrid(2, 4); const handleColumnCreate = () => { return { type: 'date', defaultValue: '01/01/2023', }; }; const dataGridProps = useDataGrid({ initialData: data, onColumnCreate: handleColumnCreate, }); return ; }; ``` ### onDelete The `onDelete` prop is a callback function passed into `useDataGrid`. When any cells are deleted, the function is called and two arguments are provided. The first argument is an array of objects that contain the `row` and `col` indexes of the cells being deleted, along with the corresponding deleted cell `value`. The second argument is the post-delete grid data. ```typescript ( deletedCells?: { row: number, col: number, value: any }[], data?: any[][] ) ``` ```jsx live-in-view () => { const { data } = utils.useDocDataGrid(6, 4); const onDelete = (deletedCells, data) => { console.log({ deletedCells, data }); }; const dataGridProps = useDataGrid({ initialData: data, onDelete, }); return ; }; ``` ```jsx render void', description: 'Callback fired each time user deletes cells', }, { name: 'readOnly', type: 'boolean', description: 'Place all content cells within the DataGrid into read-only mode', }, ]} /> ``` ```jsx render ``` ```jsx live-in-view () => { const { data } = utils.useDocDataGrid(20, 6); const dataGridProps = useDataGrid({ initialData: data, columnSort: true, columnFilter: true, }); return ( ); }; ``` ```jsx render ``` #### Additional MacOS context menu option: Shift + F10 `Shift + F10` can also trigger the context menu. This requires the Mac's keyboard be set to support F1-F12 (or F15) to as standard function keys. According to MacOS User Guide in Use keyboard function keys on Mac: - On your Mac, choose Apple menu > System Settings, then click Keyboard in the sidebar. (You may need to scroll down.) - Click Keyboard Shortcuts, then click Function Keys in the sidebar. - Turn on “Use F1, F2, etc. keys as standard function keys.” ```jsx render ``` --- id: data-table category: Data Display title: DataTable description: Displays a matrix of information with columns, rows, and information that can operate dynamically. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=3139-23110 --- ```jsx import { DataTable } from '@uhg-abyss/web/ui/DataTable'; import { useDataTable } from '@uhg-abyss/web/hooks/useDataTable'; ``` ## Usage DataTable requires usage of the `useDataTable` hook. All available props as displayed within the API integration tab and shown in the examples below must be passed into `useDataTable`. The return should then be supplied to the `tableState` prop within the `DataTable` component. The data table's features are ideal for organizing and displaying data in a UI. The column headers can sort data in ascending or descending order, rows can be expanded to progressively disclose information, and single or batch actions can be taken on rows. The data table toolbar gives a location for primary buttons, search, filtering, table display settings, and other utilities. Data tables should be used to organize and display data. They are ideal if your user must navigate to a specific piece of data to complete a task or if you need to display all of a user's resources. Data tables should be not be used when a more complex display of the data or interactions are required or as a replacement for a spreadsheet application. Data tables should be placed in a page's main content area and given plenty of space to display data without truncation. Avoid placing data tables inside modals or smaller containers where the information can feel cramped or needs truncation. The data table `title` prop is required and applied as an aria-label to the root `

` element but if you'd like to hide the title header pass in the `hideTitleHeader` prop. Below is an example of data table component that utilizes other Abyss components like [Badge](/web/ui/badge), [Icon](/web/ui/icon-material), and [Link](/web/ui/link) as a cell item. For data table cells that overflow you can use leverage the [Link](/web/ui/link) and [Drawer](/web/ui/Drawer) component to display additional data. The [Drawer](/web/ui/Drawer) components content is fully customizable, currently represented in list of values. ```jsx live () => { const getRandomVariant = () => { const variants = [`success`, `warning`, `error`, `info`, `neutral`]; const random = Math.floor(Math.random() * 5); return variants[random]; }; const getRandomBool = () => { return Math.random() < 0.5; }; const getOverFlowData = (row) => { let value; if (row % 2 === 0) { value = []; for (let i = 0; i < 10; i++) { const random = Math.floor(Math.random() * (row * (i + 2))); const temp = 160409583 + i + 1 + random; value.push(temp); } } else { const random = Math.floor(Math.random() * row); value = 161585930 + random; } return value; }; const createData = (count) => { const data = []; for (let i = 0; i < count; i++) { const variant = getRandomVariant(); data.push({ col1: `Col 1/Row ${i + 1}`, col2: 'Table Data', col3: 'Table Data', col4: getOverFlowData(i + 1), col5: variant, col6: 'Table Data', col7: getRandomBool(), }); } return data; }; const columns = React.useMemo( () => [ { Header: (

Table Data 1

What is this? ), accessor: 'col1', canToggleVisibilty: false, isHiddenByDefault: false, }, { Header: 'Table Data 2', accessor: 'col2', canToggleVisibilty: true, isHiddenByDefault: false, disableSortBy: true, canReorderColumn: false, hiddenDefaultFilters: ['greater'], customAPIFilters: [ { value: 'includes', label: 'Includes', }, ], Cell: ({ value }) => { return ( {value} ); }, }, { Header: 'Table Data 3', accessor: 'col3', canToggleVisibilty: true, isHiddenByDefault: false, label: 'Table Data 3', Cell: ({ value }) => { return {value}; }, }, { Header: 'Overflow Data', accessor: 'col4', canToggleVisibilty: true, isHiddenByDefault: false, disableSortBy: true, canReorderColumn: false, Cell: ({ value, row }) => { const isArray = Array.isArray(value); if (isArray && !value.length) return ''; return ( {isArray ? value[0] : value} {isArray && ( drawer.open({ value })} aria-haspopup="dialog" > See All )} ); }, }, { Header: 'Table Data 5', accessor: 'col5', canToggleVisibilty: true, isHiddenByDefault: false, disableSortBy: true, canReorderColumn: false, Cell: ({ value }) => { const badgeLabel = value.charAt(0).toUpperCase() + value.slice(1); return {badgeLabel} Badge; }, }, { Header: 'Table Data 6', accessor: 'col6', canToggleVisibilty: true, isHiddenByDefault: false, disableSortBy: true, canReorderColumn: false, Cell: ({ value }) => { return ( {value} ); }, }, { Header: 'Favorite', accessor: 'col7', canToggleVisibilty: true, isHiddenByDefault: false, disableSortBy: true, canReorderColumn: false, sortType: 'basic', minWidth: 100, width: 100, disableResizing: true, Cell: ({ value, cellActions, row, ...props }) => { return ( Add To Favorites { cellActions.modifyRow(row, { col7: !value }); }} style={{ height: '25px', overflow: 'hidden', position: 'absolute', width: '25px', cursor: 'pointer', }} /> ); }, }, ], [] ); const data = React.useMemo(() => [...createData(200)], []); const bulkActions = [ { onClick: ({ deleteRows }) => { deleteRows(); }, icon: , label: 'Delete Rows', isSeparated: true, }, { onClick: ({ modifyRows }) => { modifyRows({ col1: 'Modified Cell' }); }, label: 'Modify Cells', }, { onClick: ({ modifyRows }) => { modifyRows({ col1: `Modified Col 1`, col2: `Modified Col 2`, col3: `Modified Col 3`, }); }, label: 'Modify Rows', icon: , isSingle: true, }, ]; const individualActions = [ { onClick: ({ deleteRow, row }) => { deleteRow(row); }, checkDisabled: (row) => { return row.index % 4 === 0; }, icon: , label: 'Delete Row', isSeparated: true, }, { onClick: ({ modifyRow, row }) => { modifyRow(row, { col1: 'Modified Cell' }); }, label: 'Modify Cell', }, { onClick: ({ modifyRow, row }) => { modifyRow(row, { col1: `Modified Col 1`, col2: `Modified Col 2`, col3: `Modified Col 3`, }); }, label: 'Modify Row', icon: , }, ]; const dataTableProps = useDataTable({ initialData: data, initialColumns: columns, showSelection: true, bulkActions, individualActions, showPagination: true, showGlobalFilter: true, showTableSettings: true, showFullscreenButton: true, highlightRowOnHover: true, showDownloadButton: true, showFilterDataset: true, showColumnVisibilityConfig: true, additionalPaginationText: '(Can insert extra text here)', uniqueStorageId: 'data-table-usage', onColumnVisibilityClose: (columns) => console.log( 'columns on close', columns, dataTableProps.columnMgmt.allColumns ), onColumnVisibilityOpen: (columns) => console.log( 'columns on open', columns, dataTableProps.columnMgmt.allColumns ), }); const drawer = useOverlay('cellOverflow-drawer'); const { data: drawerData } = drawer.getState(); return ( {drawerData && drawerData.value.map((item) => { return (

{item}

); })} ); }; ``` ## Table settings Use the `showColumnVisibilityConfig` prop to allow the users to customize the visibility and order of the columns. You can restrict the users ability to toggle visibility and reorder columns by passing in the `canToggleVisibility` and `canReorderColumn` respectively in the column config. Use the `isHiddenByDefault` column prop to have a set of columns that are hidden by default that the user can toggle on/off. Pass `showColumn` set to `true` to override the `isHiddenByDefault` config. If you need the current configuration of the columns pass a callback function to the `onColumnVisibilityClose` prop to receive the most recent columns on close of the column management drawer. To automatically store the column order and visibility, pass the `uniqueStorageId` prop to have the config stored locally. Please note that when the `uniqueStorageId` prop is used, once the user begins updating column visibility, the updates are written into local storage and will take precedence over the initial configuration of column visibility. If you need the current configuration of the columns pass a callback function to the `onColumnVisibilityOpen` prop to receive the most recent columns on open of the column management drawer. If you want to turn a column into a row header, pass the `isRowHeader: true` prop to an individual column. ```jsx live-in-view () => { const { data } = utils.useDocDataTable(5, 4); const columns = React.useMemo( () => [ { Header: 'Column 1', accessor: 'col1', canToggleVisibilty: false, isHiddenByDefault: false, canReorderColumn: false, }, { Header: 'Column 2', accessor: 'col2', canToggleVisibilty: true, isHiddenByDefault: true, showColumn: true, disableSortBy: true, canReorderColumn: false, }, { Header: 'Column 3', accessor: 'col3', canToggleVisibilty: true, isHiddenByDefault: false, canReorderColumn: true, label: 'HSA', }, { Header: 'Column 4', accessor: 'col4', canToggleVisibilty: true, isHiddenByDefault: true, disableSortBy: true, canReorderColumn: true, }, ], [] ); const dataTableProps = useDataTable({ initialData: data, initialColumns: columns, showColumnVisibilityConfig: true, showPagination: false, uniqueStorageId: 'data-table-local-storage', onColumnVisibilityClose: (columns) => console.log('columns', columns), onColumnVisibilityOpen: (columns) => console.log('columns', columns), }); console.log(dataTableProps); const handleOnClick = () => { dataTableProps.setColumns(newColumns, true); dataTableProps.setData(newData, true); }; return ; }; ``` ## Table data ### Initial data Use the `initialData` and `initialColumns` to set the initial state of your `DataTable`. Update data using the `setColumns` and `setData` methods mentioned above. **Note:** When using the `defaultPage` prop in conjunction with `setData` or `setColumns`, you need to ensure you are passing the second parameter as `true`: `setData(newData, true)` the same way shown in the example below. ```jsx live-in-view () => { const { data: newData, columns: newColumns } = utils.useDocDataTable(25); const dataTableProps = useDataTable({ showColumnSort: true, showPagination: true, initialData: [ { col1: 'Initial Col 1/Row 1', col2: 'Initial Col 2/Row 1', }, { col1: 'Initial Col 1/Row 2', col2: 'Initial Col 2/Row 2', }, { col1: 'Initial Col 1/Row 3', col2: 'Initial Col 2/Row 3', }, { col1: 'Initial Col 1/Row 4', col2: 'Initial Col 2/Row 4', }, { col1: 'Initial Col 1/Row 5', col2: 'Initial Col 2/Row 5', }, ], initialColumns: [ { Header: 'Initial Column 1', accessor: 'col1', }, { Header: 'Initial Column 2', accessor: 'col2', }, ], showSelection: true, }); const handleOnClick = () => { dataTableProps.setColumns(newColumns, true); dataTableProps.setData(newData, true); }; return ( ); }; ``` ### Updating table data Use the `setColumns` and `setData` methods to update the columns and rows in that table. Do not mutate initial state data as a way to update `DataTable`. `setData` is not compatible with `apiPaginationCall` and server-side-pagination. A second parameter of type `boolean` can be passed to `setColumns` and `setData` to skip page reset, the default is `false`. ```jsx live-in-view () => { const { data, columns } = utils.useDocDataTable(5); const { data: newData } = utils.useDocDataTable(25); const dataTableProps = useDataTable({ showColumnSort: true, showPagination: true, initialData: data, initialColumns: columns, showSelection: true, }); const handleOnClick = () => { dataTableProps.setData(newData, true); }; return ( ); }; ``` ```jsx live-in-view () => { const { data, columns } = utils.useDocDataTable(5); const newColumns = [ { Header: 'New Column 1', accessor: 'col1', }, { Header: 'New Column 2', accessor: 'col2', }, ]; const dataTableProps = useDataTable({ showColumnSort: true, showPagination: true, initialData: data, initialColumns: columns, showSelection: true, }); const handleOnClick = () => { dataTableProps.setColumns(newColumns, true); }; return ( ); }; ``` ## Sizing, order, and display ### Reorder rows Using the `reorderRows` prop you can reorder rows in the table by dragging draggable icon in first column. `reorderRows` is **not** compatible with `enableGroupBy`. The default value is `false`. The `onRowOrderChange` is a callback function that is triggered when a row is reordered. It has three parameters: `source` (row index before), `destination`(row index after), and `dragData`. ```jsx live-in-view () => { const { data } = utils.useDocDataTable(50, 3); const columns = React.useMemo( () => [ { Header: 'Column 1', accessor: 'col1', canToggleVisibilty: false, }, { Header: 'Column 2', accessor: 'col2', canToggleVisibilty: false, }, { Header: 'Column 3', accessor: 'col3', canToggleVisibilty: false, }, ], [] ); const dataTablePropsPagination = useDataTable({ showPagination: true, initialData: data, initialColumns: columns, showTableSettings: true, pageSizeOptions: [5, 10, 15], reorderRows: true, onRowOrderChange: (source, destination, dragData) => { console.log( `Row ${source} moved to ${destination}. Here is the dragged data: `, dragData ); }, }); return ( ); }; ``` ### Resize columns You can resize columns in the table by clicking and dragging the divider between two column headers. To disable resizing across the entire table, pass `disableResizing: true` into the table options, or to prevent a specific column from being resized, pass `disableResizing: true` into its respective column object. ```jsx live-in-view () => { const { data } = utils.useDocDataTable(50, 3); const columns = React.useMemo( () => [ { Header: 'Non-resizable column', accessor: 'col1', canToggleVisibilty: false, disableResizing: true, }, { Header: 'Resizable Column 1', accessor: 'col2', canToggleVisibilty: false, }, { Header: 'Resizable Column 2', accessor: 'col3', canToggleVisibilty: false, }, ], [] ); const dataTablePropsPagination = useDataTable({ showPagination: true, initialData: data, initialColumns: columns, showTableSettings: true, pageSizeOptions: [5, 10, 15], }); return ( ); }; ``` ```jsx live-in-view () => { const { data } = utils.useDocDataTable(50, 3); const columns = React.useMemo( () => [ { Header: 'Table Resizing Disabled', accessor: 'col1', canToggleVisibilty: false, }, { Header: 'Non-resizable Column 2', accessor: 'col2', canToggleVisibilty: false, }, { Header: 'Non-resizable Column 3', accessor: 'col3', canToggleVisibilty: false, }, ], [] ); const dataTablePropsPagination = useDataTable({ showPagination: true, initialData: data, initialColumns: columns, disableResizing: true, showTableSettings: true, pageSizeOptions: [5, 10, 15], }); return ( ); }; ``` ### Default column widths and overrides Use the `minColumnWidth` prop to set the minimum column width for columns in the table. The default value is `150` pixels. Each individual column can receive the `minWidth`, `width`, and `maxWidth` properties to set their minimum, default, and maximum widths respectively. ```jsx live-in-view () => { const { data } = utils.useDocDataTable(50, 5); const columns = React.useMemo( () => [ { Header: 'Default column widths (150px)', accessor: 'col1', }, { Header: 'Max Width: 300px', accessor: 'col2', maxWidth: 300, }, { Header: 'Starting Width: 250px', accessor: 'col3', width: 250, }, { Header: 'Min Width: 200px', accessor: 'col4', minWidth: 200, }, ], [] ); const dataTablePropsPagination = useDataTable({ showPagination: true, initialData: data, initialColumns: columns, pageSizeOptions: [5, 10, 15], minColumnWidth: 150, }); return ( ); }; ``` ### Fullscreen Use the `showFullscreenButton` prop to show a button that will render the table in fullscreen when clicked. The default value is `false`. ```jsx live-in-view () => { const { data } = utils.useDocDataTable(50, 3); const columns = React.useMemo( () => [ { Header: 'Column 1', accessor: 'col1', canToggleVisibilty: false, }, { Header: 'Column 2', accessor: 'col2', canToggleVisibilty: false, }, { Header: 'Column 3', accessor: 'col3', canToggleVisibilty: false, }, ], [] ); const dataTablePropsPagination = useDataTable({ showPagination: true, initialData: data, initialColumns: columns, showFullscreenButton: true, pageSizeOptions: [10, 20, 30], }); return ( ); }; ``` ### Display settings Set the `showTableSettings` prop to true to display a drop-down menu for table configuration settings above the table, allowing the user to hide empty columns and resize cells to `Comfortable` (48px) `Cozy` (40px) or `Compact` (34px). By default, empty columns are displayed and the cell height is set to `Comfortable`. Add the `highlightRowOnHover` prop and set to true to add highlighting of the table rows on hover. Use the `defaultTableSettings` prop to configure these default values programmatically. The `defaultTableSettings` prop must be an object with the following structure: ```ts { hideEmptyColumns?: boolean, rowHeight?: 'comfortable' | 'cozy' | 'compact', } ``` ```jsx live-in-view () => { const getRandomVariant = () => { const variants = [`success`, `warning`, `error`, `info`, `neutral`]; const random = Math.floor(Math.random() * 5); return variants[random]; }; const createData = (count) => { const data = []; for (let i = 0; i < count; i++) { const variant = getRandomVariant(); data.push({ col1: `Col 1/Row ${i + 1}`, col2: 'Table Data', col3: null, col4: variant, col5: null, }); } return data; }; const columns = React.useMemo( () => [ { Header: 'Table Data 1', accessor: 'col1', canToggleVisibilty: false, isHiddenByDefault: false, }, { Header: 'Table Data 2', accessor: 'col2', canToggleVisibilty: true, isHiddenByDefault: false, disableSortBy: true, canReorderColumn: false, Cell: ({ value }) => { return ( {value} ); }, }, { Header: 'Table Data 3', accessor: 'col3', canToggleVisibilty: true, isHiddenByDefault: false, label: 'Table Data 3', }, { Header: 'Table Data 4', accessor: 'col4', canToggleVisibilty: true, isHiddenByDefault: false, disableSortBy: true, canReorderColumn: false, Cell: ({ value }) => { const badgeLabel = value.charAt(0).toUpperCase() + value.slice(1); return {badgeLabel} Badge; }, }, ], [] ); const data = React.useMemo(() => [...createData(10)], []); const dataTableProps = useDataTable({ initialData: data, initialColumns: columns, showPagination: false, showTableSettings: true, highlightRowOnHover: true, defaultTableSettings: { hideEmptyColumns: true, rowHeight: 'cozy', }, }); return ( ); }; ``` ## Download table Use the `showDownloadButton` prop to show a dropdown menu that allows you to download the table data. The default value is `false`. See [Custom CSV](#custom-csv) for more information on how to apply custom rendering to the table data csv file. ```jsx live-in-view () => { const { data } = utils.useDocDataTable(1000, 3); const columns = React.useMemo( () => [ { Header: 'Column 1', accessor: 'col1', canToggleVisibilty: false, }, { Header: 'Column 2', accessor: 'col2', canToggleVisibilty: false, }, { Header: 'Column 3', accessor: 'col3', canToggleVisibilty: false, }, ], [] ); const dataTablePropsPagination = useDataTable({ showPagination: true, initialData: data, initialColumns: columns, showDownloadButton: true, pageSizeOptions: [10, 20, 30], showGlobalFilter: true, }); return ( ); }; ``` ### Remove CSV columns Use the `removeCsvColumns` prop to remove columns from the csv download. The `removeCsvColumns` prop takes an array containing the accessor values from the columns you would like removed. ```jsx live-in-view () => { const { data } = utils.useDocDataTable(1000, 3); const columns = React.useMemo( () => [ { Header: 'Column 1', accessor: 'col1', canToggleVisibilty: false, }, { Header: 'Column 2', accessor: 'col2', canToggleVisibilty: false, }, { Header: 'Remove on CSV Download', accessor: 'col3', canToggleVisibilty: false, }, ], [] ); const dataTablePropsPagination = useDataTable({ showPagination: true, initialData: data, initialColumns: columns, showDownloadButton: true, pageSizeOptions: [10, 20, 30], showGlobalFilter: true, removeCsvColumns: ['col3'], }); return ( ); }; ``` ### Download button config Use the `downloadButtonConfig` prop to remove or add custom actions to the existing csv download options. `downloadButtonConfig` must be an object with the following structure: ```jsx const dataTablePropsPagination = useDataTable({ ... // Other props for useDataTable go here downloadButtonConfig: { filteredCsvFileName: 'tableData.csv', // custom name for filtered dataset CSV file; default is 'tableData.csv' fullCsvFileName: 'tableData.csv', // custom name for full dataset CSV file; default is 'tableData.csv' removeFiltered: false, // remove "Download filtered dataset (CSV)" option; default is false removeFull: false, // remove "Download full dataset (CSV)" option; default is false custom: { // optional custom action; can also be an array of objects title: 'Option Title', // option item title icon: // option item icon onClick: () => { // perform action } }, } }); ``` ```jsx live-in-view () => { const getMockData = utils.useDataTableApiMock(); const getFullDataSet = utils.useDataTableApiMock({ returnFullData: true }); const [isLoading, setIsLoading] = useState(false); const columns = React.useMemo( () => [ { Header: 'Name', accessor: 'name', }, { Header: 'Sort Order', accessor: 'sortOrder', }, ], [] ); const customDownloadOption = { title: 'Custom - Download Full Dataset (CSV)', icon: , onClick: () => { setIsLoading(true); getFullDataSet().then((res) => { console.log('all row data', res.results); dataTableProps.downloadCSV( res.results, dataTableProps.reactTableProps.visibleColumns, dataTableProps.removeCsvColumns, 'customFull.csv' ); setIsLoading(false); }); }, }; const dataTableProps = useDataTable({ initialColumns: columns, showSelection: true, showPagination: true, pageSizeDefault: 5, pageSizeOptions: [5, 10], defaultSelectedRows: { 1: true, }, uniqueStorageId: 'custom-download-server-side', apiPaginationCall: getMockData, manualSortBy: true, showGlobalFilter: true, showDownloadButton: true, downloadButtonConfig: { filteredCsvFileName: 'filtered.csv', removeFull: true, custom: customDownloadOption, }, }); return ( ); }; ``` ### Custom CSV The `customSetCsv` prop is a callback function that returns the cell value (within a `value` property) when downloading the table data CSV file. Use this whenever you're performing any custom rendering within `Cell` to ensure the data is also properly rendered within the CSV. Download the CSV file for the example below to see the application of this prop and how the column without `customSetCsv` attempts to render the full object. The callback also receives the entire row data (within a `row` property), allowing you to generate cell values in the CSV that depend on information from other columns in the same row. ```jsx live-in-view () => { const createData = (count) => { const data = []; for (let i = 0; i < count; i++) { data.push({ col1: { colName: 'Col 1', rowName: `Row ${i + 1}` }, col2: { colName: 'Col 2', rowName: `Row ${i + 1}` }, }); } return data; }; const renderColData = ({ value }) => { const { colName, rowName } = value; return `${colName} / ${rowName}`; }; const formatColValue = ({ value, row }) => { const col2 = row.col2; const { colName, rowName } = value; return `${colName} / ${rowName} Col2 Data: ${col2.colName} / ${col2.rowName}`; }; const columns = React.useMemo( () => [ { Header: 'Column With Custom CSV', accessor: 'col1', canToggleVisibilty: false, customSetCsv: formatColValue, Cell: renderColData, }, { Header: 'Column Without Custom CSV', accessor: 'col2', canToggleVisibilty: false, Cell: renderColData, }, ], [] ); const data = React.useMemo(() => [...createData(10)], []); const dataTablePropsPagination = useDataTable({ showPagination: false, initialData: data, initialColumns: columns, showDownloadButton: true, }); return ; }; ``` ## Sorting ### Column sort Use the `showColumnSort` prop to either turn off or on the ability for the user to sort columns. Pass the `disableSortBy` prop to the column config to toggle the ability to sort or not sort the columns. ```jsx live-in-view () => { const { data, columns } = utils.useDocDataTable(5); const dataTableProps = useDataTable({ showColumnSort: false, showPagination: false, initialData: data, initialColumns: columns, }); const dataTablePropsSort = useDataTable({ showColumnSort: true, showPagination: false, initialData: data, initialColumns: columns, }); return ( ); }; ``` ### Sorting programmatically It is also possible to control column sorting programmatically using the `columnMgmt.setSortBy` function returned from `useDataTable`. ```jsx live-in-view () => { const { data, columns } = utils.useDocDataTable(5); const dataTableProps = useDataTable({ showColumnSort: true, showPagination: false, initialData: data, initialColumns: columns, }); const toggleSort = () => { const sortDir = dataTableProps.state.sortBy.length > 0 ? !dataTableProps.state.sortBy[0].desc : false; dataTableProps.columnMgmt.setSortBy([{ id: 'col1', desc: sortDir }]); }; return ( ); }; ``` ### SortType Pass the `sortType` prop to the column config to sort the column data. It takes following parameters: - `alphanumeric`: Sorts by mixed alphanumeric values with case-sensitivity. - `alphanumericCaseInsensitive`: Sorts by mixed alphanumeric values without case-sensitivity. - `datetime`: Sorts by date/time; values must be Date objects. The default value is `alphanumericCaseInsensitive`. ```jsx live-in-view () => { const getRandomVariant = () => { const variants = [1, 3, 'Alpha', 'beta', 'Charlie', 'Theta']; const random = Math.floor(Math.random() * 5); return variants[random]; }; const randomDate = (start, end) => { return new Date( start.getTime() + Math.random() * (end.getTime() - start.getTime()) ); }; const createData = (count) => { const data = []; for (let i = 0; i < count; i++) { const variant = getRandomVariant(); const date = randomDate(new Date('01/01/2021'), new Date()); data.push({ col1: variant, col2: variant, col3: date, }); } return data; }; const columns = React.useMemo( () => [ { Header: 'Table Data 1', accessor: 'col1', // Default Sort Type // sortType: 'alphanumericCaseInsensitive', }, { Header: 'Table Data 2', accessor: 'col2', sortType: 'alphanumeric', }, { Header: 'Table Data 3', accessor: 'col3', sortType: 'datetime', Cell: ({ value }) => { return dayjs(value).format('MM/DD/YYYY'); }, }, ], [] ); const data = React.useMemo(() => [...createData(10)], []); const dataTableProps = useDataTable({ initialData: data, initialColumns: columns, showPagination: false, showGlobalFilter: true, showFilterDataset: true, filterColumnTypes: { col3: { type: 'date', }, }, }); return ; }; ``` ## Actions ### Bulk actions Use the `bulkActions` prop to add table actions to selected row. Each action's `onClick` function will be passed an object as a parameter, which has the following properties: Main properties: - `deleteRows` - a function that deletes the selected rows. - `modifyRows` - a function to modify multiple cells of the selected rows. Takes one parameter, an object where the keys are column IDs to be modified, and their respective values are what the cells will be changed to. - `modifyRow` - a function similar to modifyRows but allows you to designate the specific rows to modify from the selected group. Takes two parameters, the id of the row to be modified and an object where the keys are column IDs to be modified, and their respective values are what the cells will be changed to. Other properties: - `getSelectedRowIds` - a function that returns IDs of the selected rows. - `clearSelectedRows` - a function that clears the selected rows. - `getSelectedRows` - a function that returns the row object of selected rows. Does not work when [server-side pagination](#server-side-pagination) is active. - `clearCache` - a function that can be called when using [server-side pagination](#server-side-pagination) to clear the cached data. This would be useful if you call your API to update the selected rows (using `getSelectedRowIds`), so you can empty the cache and retrieve the updated data from the API. Each action must include a label and an icon. Pass the `isSingle` flag into any action to disable the button if the user has more than one row selected. Pass the `isSeparated` flag into any action to create a horizontal divider between that action and the next action. ```jsx live-in-view () => { const { data, columns } = utils.useDocDataTable(100); const bulkActions = [ { onClick: ({ deleteRows, getSelectedRowIds, clearCache }) => { console.log('Deleting rows: ', getSelectedRowIds()); deleteRows(); }, icon: , label: 'Delete Rows', isSeparated: true, }, { onClick: ({ modifyRows, getSelectedRowIds, clearCache }) => { console.log('Modifying cells in rows: ', getSelectedRowIds()); modifyRows({ col1: 'Modify Cell' }); }, icon: , label: 'Modify Cells', }, { onClick: ({ modifyRows, getSelectedRowIds, clearCache, getSelectedRows, }) => { console.log('getSelectedRows', getSelectedRows()); const ids = getSelectedRowIds(); modifyRows({ col1: `Modified Col1/Row id: ${ids[0]}`, col2: `Modified Col2/Row id: ${ids[0]}`, col3: `Modified Col3/Row id: ${ids[0]}`, }); }, label: 'Modify Rows', isSingle: true, }, ]; const dataTableProps = useDataTable({ initialData: data, initialColumns: columns, showSelection: true, defaultSelectedRows: { 1: true, 6: true }, bulkActions, }); return ; }; ``` Use `modifyRow` whenever you need to control which rows from the selected group should be modified. You can dynamically enable or disable a bulk action option based on selected row data by passing a function to the `disableOnRowCondition` prop. The function must take in a `rows` parameter and return a boolean. ```jsx live-in-view () => { const [isLoading, setLoading] = useState(false); const createData = (count) => { const data = []; for (let i = 0; i < count; i++) { data.push({ col1: `Col 1/Row ${i + 1}`, }); } return data; }; const data = React.useMemo(() => [...createData(10)], []); const columns = React.useMemo( () => [ { Header: 'Column 1', accessor: 'col1', canToggleVisibilty: false, isHiddenByDefault: false, canReorderColumn: false, }, { Header: 'Status', accessor: 'col2', canToggleVisibilty: false, isHiddenByDefault: false, canReorderColumn: false, }, ], [] ); const modifySpecifiedRows = ({ getSelectedRowIds, getSelectedRows, modifyRow, }) => { setLoading(true); setTimeout(() => { setLoading(false); const selectedRowIds = getSelectedRowIds(); const selectedRows = getSelectedRows(); console.log('getSelectedRows', selectedRows); console.log('getSelectedRowIds', selectedRowIds); selectedRows.forEach((row, index) => { const rowId = selectedRowIds[index]; if (rowId % 2 === 0) { modifyRow(rowId, { col2: Failed to Complete, }); } else { modifyRow(rowId, { col2: Completed Successfully, }); } }); }, 1000); }; const selectedRowAlreadyModified = (rows) => { if (rows) { const result = rows.filter((row) => row.col2 != undefined); if (result.length > 0) { return true; } } return false; }; const bulkActions = [ { onClick: modifySpecifiedRows, label: 'Modify Specified Rows', disableOnRowCondition: selectedRowAlreadyModified, }, ]; const dataTableProps = useDataTable({ initialData: data, initialColumns: columns, showSelection: true, showPagination: false, defaultSelectedRows: { 1: true, 6: true }, bulkActions, }); return ( ); }; ``` ### Individual actions Use the `individualActions` prop to add table actions to individual rows. When `individualActions` is used an 'Actions' column will appear in the table. If an array of action objects is added to `individualActions` each row will have its own [DropDownMenu](/web/ui/dropdown-menu) that includes each of the actions within `individualActions`. Use the `actionsMenuOnOpenChange` callback function to help track when the menu is opened. It has two parameters: isOpen (boolean) and row (object). If only a single action object is added, rather than a dropdown menu the action will be converted to a single button in the style of either a [Button](/web/ui/button) or [Link](web/ui/link) based on the `buttonVariant` prop value. The single action default style type is link. Each action's `onClick` function will be passed an object as a parameter, which has the following properties: - `row` - the row being interacted with. You will almost always want to pass this into `deleteRow` or `modifyRow` as the row being modified / deleted. - `deleteRow` - a function that deletes a row. Takes one parameter, the row to delete. - `modifyRow` - a function to modify cells in a row. Takes two parameters; the first one is the row to modify, and the second is an object where the keys are column IDs to be modified, and their respective values are what the cells will be changed to. - `clearCache` - a function that can be called when using [server-side pagination](#server-side-pagination) to clear the cached data. This would be useful if you call your API to update the data, so you can empty the cache and retrieve the updated data from the API. - `clearSelectedRows` - a function that clears the selected rows. You may provide a `checkDisabled` function to the action, which takes `row` as a parameter and must return `true` or `false`. If it returns `true`, the action will be disabled for that row. Use this function to determine if an action should be disabled; for example, if your table has emails as data and a specific email is marked as read, you would want to disable the action to mark it as read (using `checkDisabled` to check the read / unread field in the row data). Each action must include a label and an icon. Pass the `isSeparated` flag into any action to create a horizontal divider between that action and the next action. ```jsx live-in-view () => { const { data, columns } = utils.useDocDataTable(100); const individualActions = [ { onClick: ({ deleteRow, row }) => { deleteRow(row); console.log('deleted row: ', row); }, checkDisabled: (row) => { return row.index % 4 === 0; }, icon: , label: 'Delete Row', isSeparated: true, }, { onClick: ({ modifyRow, row }) => { modifyRow(row, { col1: 'Modified Cell' }); }, label: 'Modify Cell', }, { onClick: ({ modifyRow, row }) => { modifyRow(row, { col1: `Modified Col 1`, col2: `Modified Col 2`, col3: `Modified Col 3`, }); }, label: 'Modify Row', icon: , }, ]; const dataTableProps = useDataTable({ initialData: data, initialColumns: columns, showSelection: true, individualActions, actionsMenuOnOpenChange(isOpen, row) { console.log('Row ', row, 'isOpen: ', isOpen); }, }); return ( ); }; ``` To use a single action in the style of a [Link](/web/ui/link) simply pass in a single object and it will default to the style of a link. ```jsx live-in-view () => { const { data, columns } = utils.useDocDataTable(5); const deleteLinkButton = { onClick: ({ deleteRow, row }) => { deleteRow(row); console.log('deleted row: ', row); }, checkDisabled: (row) => { return row.index % 4 === 0; }, label: 'Delete', }; const dataTableProps = useDataTable({ initialData: data, initialColumns: columns, showSelection: true, individualActions: [deleteLinkButton], }); return ( ); }; ``` To use a single action in the style of a [Button](/web/ui/button) pass in a single object and set the `buttonVariant` prop to `true`. ```jsx live-in-view () => { const { data, columns } = utils.useDocDataTable(5); const deleteButton = [ { onClick: ({ deleteRow, row }) => { deleteRow(row); console.log('deleted row: ', row); }, checkDisabled: (row) => { return row.index % 4 === 0; }, buttonVariant: true, label: 'Delete', }, ]; const dataTableProps = useDataTable({ initialData: data, initialColumns: columns, showSelection: true, individualActions: deleteButton, }); return ( ); }; ``` ## Custom table header ### Custom table header section Use the `customHeaderSection` prop to add custom content to the left side of the table header. If [Bulk Actions](#bulk-actions) and/or [Custom Header Buttons](#custom-table-header-buttons) are utilized their corresponding buttons will appear to the right of this content. ```jsx live-in-view () => { const columns = React.useMemo( () => [ { Header: 'Column 1', accessor: 'col1', }, { Header: 'Column 2', accessor: 'col2', }, ], [] ); const createData = (dataSetValue) => { const data = []; for (let i = 0; i < 10; i++) { data.push({ col1: `Data Set ${dataSetValue} - Col 1/Row ${i + 1}`, col2: `Data Set ${dataSetValue} - Col 2/Row ${i + 1}`, }); } return data; }; const [isLoading, setLoading] = useState(false); const form = useForm({ defaultValues: { 'custom-header-section': '1', }, }); const updateTableData = () => { setLoading(true); setTimeout(() => { const currentValue = form.getValues('custom-header-section'); const data = createData(currentValue); dataTableProps.setData(data); setLoading(false); form.setFocus('custom-header-section'); }, 1000); }; const customHeaderSection = ( ); const dataTableProps = useDataTable({ initialData: createData('1'), initialColumns: columns, pageSizeDefault: 5, pageSizeOptions: [5, 10], customHeaderSection, }); return ( ); }; ``` ### Custom table header buttons Use the `customHeaderButtons` prop to create custom buttons that will appear in the table header, to the right of the [Bulk Actions](#bulk-actions) dropdown (if it is there). Each custom button can either be a link (with `href`), a button (with `onClick`), or a [DropdownMenu](/web/ui/dropdown-menu) (with `dropdownItems`). `customHeaderButtons` is an array of objects, where each object takes the following properties: - `label` - the label for the button - `icon` - the icon that will be displayed to the left of the label - `isDisabled` - a boolean that will disable the button if set to `true` - ONE of the following: - `href` - a link that the page will redirect to when the button is clicked - `onClick` - a function that will be called when the button is clicked - `dropdownItems` - an array that will be used to create a [DropdownMenu](/web/ui/dropdown-menu) instead of a button; see [the docs of DropdownMenu](/web/ui/dropdown-menu) for more information on what to pass. NOTE: the maximum number of custom buttons is `2`, so any additional custom buttons included in `customHeaderButtons` will not be rendered. ```jsx live-in-view () => { const { data, columns } = utils.useDocDataTable(50); const customHeaderButtons = [ { label: 'Custom Button', onClick: () => { console.log('custom button clicked'); }, }, { label: 'Link to Abyss docs', icon: , href: 'https://abyss.uhg.com', }, ]; const dataTableProps = useDataTable({ initialData: data, initialColumns: columns, pageSizeDefault: 5, pageSizeOptions: [5, 10], customHeaderButtons, }); return ( ); }; ``` ```jsx live-in-view () => { const { data, columns } = utils.useDocDataTable(50); const customHeaderButtons = [ { label: 'Custom Dropdown', icon: , dropdownItems: [ { title: 'Test Action', onClick: () => { console.log('test action clicked'); }, icon: , }, { title: 'Disabled Test Action', onClick: () => { console.log('disabled test action clicked'); }, disabled: true, }, ], }, ]; const dataTableProps = useDataTable({ initialData: data, initialColumns: columns, pageSizeDefault: 5, pageSizeOptions: [5, 10], customHeaderButtons, }); return ( ); }; ``` ## Row selection ### Multi selection Use the `showSelection` prop to allow the ability for users to select rows. To set default selected rows use the `defaultSelectedRows` prop, `[rowId]: true/false`. ```jsx live-in-view () => { const { data, columns } = utils.useDocDataTable(20); const dataTablePropsPagination = useDataTable({ showSelection: true, defaultSelectedRows: { 1: true, 6: true }, initialData: data, initialColumns: columns, }); return (

        
          selectedRowIds:
          {JSON.stringify(
            dataTablePropsPagination.state.selectedRowIds,
            null,
            2
          )}

); }; ``` If you need the ability to control the enabled/disabled state of checkbox rows, you can pass a function into `showSelection`. This function will be called per row and will supply the row object. To disable a row's checkbox return `false`, otherwise return `true` for normal operation. ```jsx live-in-view () => { const { data, columns } = utils.useDocDataTable(20); const dataTablePropsPagination = useDataTable({ showSelection: (row) => { console.log('row', row); return row.index % 2 === 0; }, initialData: data, initialColumns: columns, }); return (

        
          selectedRowIds:
          {JSON.stringify(
            dataTablePropsPagination.state.selectedRowIds,
            null,
            2
          )}

); }; ``` ### Single selection Use the `singleSelection` prop to allow the ability for users to select only one row. ```jsx live-in-view () => { const { data, columns } = utils.useDocDataTable(100); const dataTablePropsPagination = useDataTable({ singleSelection: true, initialData: data, initialColumns: columns, }); return (

        
          selectedRowIds:
          {JSON.stringify(
            dataTablePropsPagination.state.selectedRowIds,
            null,
            2
          )}

); }; ``` If you need to control control the enabled/disabled state of a row's radio button, you can pass a function into `singleSelection`. This function will be called per row and will supply the row object. To disable a row's radio button return `false`, otherwise return `true` for normal operation. ```jsx live-in-view () => { const { data, columns } = utils.useDocDataTable(100); const dataTablePropsPagination = useDataTable({ singleSelection: (row) => { console.log('row', row); return row.index % 2 === 0; }, initialData: data, initialColumns: columns, }); return (

        
          selectedRowIds:
          {JSON.stringify(
            dataTablePropsPagination.state.selectedRowIds,
            null,
            2
          )}

); }; ``` ### Clear row selection ```jsx live-in-view () => { const { data, columns } = utils.useDocDataTable(20); const bulkActions = [ { onClick: ({ clearSelectedRows }) => { clearSelectedRows(); }, icon: , label: 'Clear Selected Rows', }, ]; const clearButton = [ { onClick: ({ clearSelectedRows }) => { clearSelectedRows(); }, buttonVariant: true, label: 'Clear', }, ]; const dataTableProps = useDataTable({ showSelection: true, defaultSelectedRows: { 1: true, 6: true }, initialData: data, initialColumns: columns, bulkActions, individualActions: clearButton, }); const clearSelectionState = () => { dataTableProps.reactTableProps.tableActions.clearSelectedRows(); }; return (

        
          selectedRowIds:
          {JSON.stringify(dataTableProps.state.selectedRowIds, null, 2)}

); }; ``` ## Expansions and grouping ### Group by Use the `enableGroupBy` prop to use row grouping and aggregation. Group by will override column order when in use. Please see [react-table](https://react-table-v7.tanstack.com/docs/api/useGroupBy#usegroupby) docs for more details and config options. ```jsx live-in-view () => { const createData = (count) => { const data = []; for (let i = 0; i < count; i++) { const statusChance = Math.random(); data.push({ age: Math.floor(Math.random() * 30), visits: Math.floor(Math.random() * 100), status: statusChance > 0.66 ? 'relationship' : statusChance > 0.33 ? 'complicated' : 'single', }); } return data; }; const data = React.useMemo(() => [...createData(75)], []); const columns = React.useMemo( () => [ { canGroupBy: true, Header: 'Age', accessor: 'age', aggregate: 'average', Aggregated: ({ value }) => `${Math.round(value * 100) / 100} (avg)`, }, { canGroupBy: true, Header: 'Visits', accessor: 'visits', // Aggregate the sum of all visits aggregate: 'sum', Aggregated: ({ value }) => `${value} (total)`, }, { Header: 'Status', accessor: 'status', }, ], [] ); const dataTableProps = useDataTable({ initialData: data, initialColumns: columns, enableGroupBy: true, initialState: { groupBy: ['status'] }, }); return ; }; ``` ### Expansion sub component Use the `renderSubComponent` prop to enable expansion components for the data table. Add the `expandedByDefault` prop set to `true` to the data objects to have the expansion open by default. Use `hideExpansion` to hide the expansion trigger on a row by row basis. ** Note: `renderSubComponent` (Expansion Sub Component) and `subRows` (Expansion Rows) cannot be used together. ** ```jsx live-in-view () => { const { columns } = utils.useDocDataTable(1000); const data = [ { col1: `Col 1/Row 1`, col2: `Col 2/Row 1`, expandedByDefault: true, }, { col1: `Col 1/Row 2`, col2: `Col 2/Row 2`, }, { col1: `Col 1/Row 3`, col2: `Col 2/Row 3`, expandedByDefault: true, hideExpansion: true, }, { col1: `Col 1/Row 4`, col2: `Col 2/Row 4`, }, ]; const renderRowSubComponent = React.useCallback((row) => { return (

        {JSON.stringify({ values: row.values }, null, 2)}

); }, []); const dataTablePropsPagination = useDataTable({ renderSubComponent: renderRowSubComponent, initialData: data, initialColumns: columns, }); return ( ); }; ``` ### Expansion rows Use the `showExpansion` prop to enable expansion rows for the data table. Add `subRows` table data to render additional sub rows. ** Note: `renderSubComponent` (Expansion Sub Component) and `subRows` (Expansion Rows) cannot be used together. ** ```jsx live-in-view () => { const { columns } = utils.useDocDataTable(1000); const data = [ { col1: 'Col 1/Row 1', col2: 'Col 2/Row 1', subRows: [ { col1: 'Sub Row (0) Col 1/Row 1', col2: 'Sub Row (0) Col 2/Row 1', subRows: [ { col1: 'Sub Row (1) Col 1/Row 1', col2: 'Sub Row (1) Col 2/Row 1', }, ], }, ], }, { col1: 'Col 1/Row 2', col2: 'Col 2/Row 2', }, { col1: 'Col 1/Row 3', col2: 'Col 2/Row 3', }, { col1: 'Col 1/Row 4', col2: 'Col 2/Row 4', subRows: [ { col1: 'Sub Row (0) Col 1/Row 4', col2: 'Sub Row (0) Col 2/Row 4', }, ], }, ]; const dataTablePropsPagination = useDataTable({ initialData: data, initialColumns: columns, showExpansion: true, }); return ( ); }; ``` ## Filtering DataTable supports both global filters and column filters to refine data searches. When a filter is active, it will appear as a [Chip](/web/ui/chip), and closing the chip will remove the filter. Use the `caseSensitiveFiltering` prop to set case sensitivity for both global and column filtering. NOTE: by default, global filters are not case sensitive and column filters are case sensitive. ```jsx live-in-view () => { const createData = (count) => { const data = []; for (let i = 0; i < count; i++) { data.push({ col1: `Col 1/Row ${i + 1}`, col2: i % 2 === 0 ? -(i * 3) : i * 3, col3: `10/${9 + Math.ceil(Math.random() * 21)}/2020`, col4: i % 3 === 0 ? 'Option 1' : 'Option 2', }); } return data; }; const columns = React.useMemo( () => [ { Header: 'Table Data 1', accessor: 'col1', canToggleVisibilty: false, isHiddenByDefault: false, }, { Header: 'Value', accessor: 'col2', canToggleVisibilty: false, isHiddenByDefault: false, }, { Header: 'Date', accessor: 'col3', canToggleVisibilty: false, isHiddenByDefault: false, }, { Header: 'Option Select', accessor: 'col4', canToggleVisibilty: false, isHiddenByDefault: false, }, ], [] ); const data = React.useMemo(() => [...createData(200)], []); const dataTablePropsPagination = useDataTable({ showPagination: true, initialData: data, initialColumns: columns, showGlobalFilter: true, showFilterDataset: true, initialGlobalFilter: '2', initialFilters: [ { columnId: 'col1', filters: [{ condition: 'ends-with', filterValue: '1' }], }, { columnId: 'col2', filters: [{ condition: 'less', filterValue: '25' }], }, { columnId: 'col3', filters: [{ condition: 'greater-equal', filterValue: '10/15/2020' }], }, { columnId: 'col4', filters: [{ condition: 'equals', filterValue: 'Option 1' }], }, ], filterColumnTypes: { col3: { type: 'date', }, col4: { type: 'select', options: [ { value: 'Option 1', label: 'Option 1' }, { value: 'Option 2', label: 'Option 2' }, ], }, }, }); return ; }; ``` ### Global filtering Use the `showGlobalFilter` prop to leverage the ability to filter the table globally (across all rows / columns). You can also use the `initialGlobalFilter` prop to set the initial value for the global filter. ```jsx live-in-view () => { const { data, columns } = utils.useDocDataTable(1000); const dataTablePropsPagination = useDataTable({ showPagination: true, initialData: data, initialColumns: columns, showGlobalFilter: true, initialGlobalFilter: '20', }); return ( ); }; ``` ### Column filtering Use the `showFilterDataset` prop to leverage the ability to filter the table by column. Clicking the **Filter Dataset** Button will open a modal where you can customize and apply the filters. When filters are active, the **Filter Dataset** button text will be updated to "Edit Filters" and indicate the number of currently active filters. All column filtering uses the "AND" condition and will be compounded. #### Initial filters You can use the `initialFilters` prop to set the initial value for the column filters. `initialFilters` must be an array of objects with the structure: ```jsx const dataTablePropsPagination = useDataTable({ ... // Other props for useDataTable go here initialFilters: [ { columnId: 'col1', // The ID of the column to apply the filter on filters: [ { condition: 'contains', // The condition to filter on filterValue: '10' // The filter value }, ... // More filters on the same column ] }, ... // More filters on other columns ], }); ``` The `condition` property within `filters` must be one of the following strings: - `equals` - Equal to - `not-equal` - Not equal to - `contains` - Contains - `greater` - Greater than - `greater-equal` - Greater than or equal to - `less` - Less than - `less-equal` - Less than or equal to - `starts-with` - Starts with - `ends-with` - Ends with Additionally, we have added the following conditions. So as not to cause breaking changes for other users, if you would like to use these new conditions, pass `addEmptyFilters` to the column config. - `is-empty` - Is empty - `not-empty` - Is not empty #### Column filter types You can use the `filterColumnTypes` prop to set the kind of filter that will show up for each column. There are three available column filter types: - **text**: Utilizes [TextInput](/web/ui/text-input) and is the default type. - **date**: Utilizes [DateInput](/web/ui/date-input) and no other properties are required. - **select**: Utilizes [SelectInput](/web/ui/select-input) and can be figured one of the two following ways: - **Standard Select**: Utilize the `options` prop and supply the desired option items list an array of objects, where object each contains a `label` and `value` key/value pair. - **Select w/API Filtering**: Utilize the `apiCallback` prop and pass in an API callback function which takes in the search input value as an argument and return an array of options, where each option item contains a `value` and `label` key/value pair. See below for an example on how to set the`filterColumnTypes` object structure and configurations of the various filter types: ```jsx const apiCallbackFunction = (searchText) => { return fetch( `${Your API Endpoint link}?searchText=${searchText}` ).then((results) => { return results // must be an array of objects where each object contains a 'value' and 'label' key/value pair }); } const dataTablePropsPagination = useDataTable({ ... // Other props for useDataTable go here filterColumnTypes: { col1: { // Column ID for the column whose filter type you want to change type: 'date' // Will change the filter to a DateInput }, col2: { // Will change the filter to a SelectInput with a fixed options list type: 'select', options: [ // Each option item must contain a 'value' and 'label' key/value pair { value: 'Option 1', label: 'Option 1' }, { value: 'Option 2', label: 'Option 2' }, ] }, col3: { // Will change the filter to a SelectInput utilizing an API to set the options list type: 'select', apiCallback: apiCallbackFunction // api call back function - see example above }, }, }); ``` ```jsx live-in-view () => { const useMultipleSelectApiColumns = false; const createData = () => { const data = []; const searchMockOne = utils.useSearchInputMock().slice(0, 5); const searchMockTwo = utils.useSearchInputMock().slice(6, 11); for (let i = 0; i < 5; i++) { data.push({ col1: new Date( `${Math.ceil(Math.random() * 12)}/${Math.ceil(Math.random() * 29)}/${ 2001 + Math.ceil(Math.random() * 20) }` ), col2: i % 7 === 0 ? 'Option 1' : 'Option 2', col3: searchMockOne[i].label, col4: `Col 4/Row ${i + 1}`, ...(useMultipleSelectApiColumns && { col5: searchMockTwo[i].label }), }); } return data; }; const columns = React.useMemo(() => { const columns = [ { Header: 'Date', accessor: 'col1', canToggleVisibilty: false, isHiddenByDefault: false, sortType: 'datetime', addEmptyFilters: true, hiddenDefaultFilters: ['contains', 'starts-with', 'ends-with'], Cell: ({ value }) => { return dayjs(value).format('MM/DD/YYYY'); }, }, { Header: 'Option Select', accessor: 'col2', canToggleVisibilty: false, isHiddenByDefault: false, }, { Header: 'Api Option Select', accessor: 'col3', addEmptyFilters: true, canToggleVisibilty: false, isHiddenByDefault: false, }, { Header: 'Text', accessor: 'col4', addEmptyFilters: true, canToggleVisibilty: false, isHiddenByDefault: false, }, ]; if (useMultipleSelectApiColumns) { columns.push({ Header: 'Api Option Select 2', accessor: 'col5', canToggleVisibilty: false, isHiddenByDefault: false, }); } return columns; }, []); const data = React.useMemo(() => [...createData()], []); const dataTablePropsPagination = useDataTable({ showPagination: true, initialData: data, initialColumns: columns, showFilterDataset: true, showGlobalFilter: true, filterColumnTypes: { col1: { type: 'date', }, col2: { type: 'select', options: [ { value: 'Option 1', label: 'Option 1' }, { value: 'Option 2', label: 'Option 2' }, ], }, col3: { type: 'select', apiCallback: utils.useSearchInputMockApiPartial(0, 5), }, ...(useMultipleSelectApiColumns && { col5: { type: 'select', apiCallback: utils.useSearchInputMockApiPartial(6, 11), }, }), }, }); return ( ); }; ``` #### Remove filter columns Use the `removeFilterColumns` prop to remove columns from the "Column Name" drop-down for filter selection inside the Filter Dataset modal. The `removeFilterColumns` prop takes an array containing the `accessor` values from the columns you would like removed. ```jsx live-in-view () => { const createData = (count) => { const data = []; for (let i = 0; i < count; i++) { data.push({ col1: `Col 1/Row ${i + 1}`, col2: i % 2 === 0 ? -(i * 3) : i * 3, col3: `10/${9 + Math.ceil(Math.random() * 21)}/2020`, col4: i % 7 === 0 ? 'Option 1' : 'Option 2', }); } return data; }; const columns = React.useMemo( () => [ { Header: 'Table Data 1', accessor: 'col1', canToggleVisibilty: false, isHiddenByDefault: false, }, { Header: 'Value', accessor: 'col2', canToggleVisibilty: false, isHiddenByDefault: false, }, { Header: 'Date', accessor: 'col3', canToggleVisibilty: false, isHiddenByDefault: false, }, { Header: 'Option Select', accessor: 'col4', canToggleVisibilty: false, isHiddenByDefault: false, }, ], [] ); const data = React.useMemo(() => [...createData(500)], []); const dataTablePropsPagination = useDataTable({ showPagination: true, initialData: data, initialColumns: columns, showFilterDataset: true, removeFilterColumns: ['col2'], filterColumnTypes: { col3: { type: 'date', }, col4: { type: 'select', options: [ { value: 'Option 1', label: 'Option 1' }, { value: 'Option 2', label: 'Option 2' }, ], }, }, }); return ( ); }; ``` #### Column filter condition removal You can use the `hiddenDefaultFilters` column option to remove default filters from the condition options for a column. As a string array, enter the filter value to remove. Here is a list of default filters: - `equals` - Equal to - `not-equal` - Not equal to - `contains` - Contains - `greater` - Greater than - `greater-equal` - Greater than or equal to - `less` - Less than - `less-equal` - Less than or equal to - `starts-with` - Starts with - `ends-with` - Ends with ```jsx const columns = React.useMemo( () => [ { Header: 'Custom Header', accessor: 'col1', }, { Header: 'Custom Header 2', accessor: 'col2', hiddenDefaultFilters: ['greater', 'greater-equal', 'less', 'less-equal'], }, ], [] ); ``` #### Add column filters programmatically The `filter` property returned by `useDataTable` contains methods for programmatically interacting with table filters. Use `filter.setFilter` to set a single column filter or `filter.setAllFilters` to set multiple. ```jsx live-in-view () => { const [value, setValue] = useState(''); const createData = (count) => { const data = []; for (let i = 0; i < count; i++) { data.push({ col1: `Col 1/Row ${i + 1}`, col2: i % 2 === 0 ? -(i * 3) : i * 3, col3: `10/${9 + Math.ceil(Math.random() * 21)}/2020`, col4: i % 7 === 0 ? 'Option 1' : 'Option 2', }); } return data; }; const columns = React.useMemo( () => [ { Header: 'Table Data 1', accessor: 'col1', canToggleVisibilty: false, isHiddenByDefault: false, }, { Header: 'Value', accessor: 'col2', canToggleVisibilty: false, isHiddenByDefault: false, }, { Header: 'Date', accessor: 'col3', canToggleVisibilty: false, isHiddenByDefault: false, }, { Header: 'Option Select', accessor: 'col4', canToggleVisibilty: false, isHiddenByDefault: false, }, ], [] ); const data = React.useMemo(() => [...createData(500)], []); const dataTableProps = useDataTable({ showPagination: true, initialData: data, initialColumns: columns, }); const filterTable = () => { dataTableProps.filter.setFilter('col1', [ { condition: 'contains', filterValue: value, }, ]); }; return ( <> setValue(e.target.value)} onClear={() => setValue('')} /> ); }; ``` ```jsx live-in-view () => { const [value, setValue] = useState(''); const createData = (count) => { const data = []; for (let i = 0; i < count; i++) { data.push({ col1: `Col 1/Row ${i + 1}`, col2: i % 2 === 0 ? -(i * 3) : i * 3, col3: `10/${9 + Math.ceil(Math.random() * 21)}/2020`, col4: i % 7 === 0 ? 'Option 1' : 'Option 2', }); } return data; }; const columns = React.useMemo( () => [ { Header: 'Table Data 1', accessor: 'col1', canToggleVisibilty: false, isHiddenByDefault: false, }, { Header: 'Value', accessor: 'col2', canToggleVisibilty: false, isHiddenByDefault: false, }, { Header: 'Date', accessor: 'col3', canToggleVisibilty: false, isHiddenByDefault: false, }, { Header: 'Option Select', accessor: 'col4', canToggleVisibilty: false, isHiddenByDefault: false, }, ], [] ); const data = React.useMemo(() => [...createData(500)], []); const dataTableProps = useDataTable({ showPagination: true, initialData: data, initialColumns: columns, }); const filterTable = () => { const filter = { id: 'col1', value: [ { condition: 'contains', filterValue: '1', }, { condition: 'contains', filterValue: '2', }, ], }; dataTableProps.filter.setAllFilters([filter]); }; return ( <> ); }; ``` ## Customizing cells ### Custom headers Use the `Header` prop to pass in a standard string or custom React Node. ```jsx live-in-view () => { const { data } = utils.useDocDataTable(5); const columns = React.useMemo( () => [ { Header: 'Custom Header', accessor: 'col1', }, { Header: 'HSA', accessor: 'col2', }, ], [] ); const dataTablePropsPagination = useDataTable({ showPagination: true, initialData: data, initialColumns: columns, }); return ( ); }; ``` ### Custom cells Use the `Cell` prop to update each of the cells in the column. ```jsx live-in-view () => { const columns = React.useMemo( () => [ { Header: 'Column 1', accessor: 'col1', Cell: ({ value }) => { if (!value) { return '--'; } return value; }, }, { Header: 'Column 2', accessor: 'col2', Cell: ({ value }) => { return ( Updated Cell: {value} ); }, }, ], [] ); const data = React.useMemo( () => [ { col1: '', col2: 'Col 2/Row 1', }, { col1: 'Col 1/Row 2', col2: 'Col 2/Row 2', }, { col1: '', col2: 'Col 2/Row 3', }, { col1: 'Col 1/Row 4', col2: 'Col 2/Row 4', }, { col1: '', col2: 'Col 2/Row 5', }, ], [] ); const dataTableProps = useDataTable({ showPagination: true, initialData: data, initialColumns: columns, }); return ; }; ``` ### Footer You can add a footer to the table by adding the `Footer` to the columns config. The `Footer` value can be a string, node, or function. ```jsx live-in-view () => { const createData = (count) => { const data = []; for (let i = 0; i < count; i++) { const statusChance = Math.random(); data.push({ age: Math.floor(Math.random() * 30), visits: Math.floor(Math.random() * 100), status: statusChance > 0.66 ? 'relationship' : statusChance > 0.33 ? 'complicated' : 'single', }); } return data; }; const data = React.useMemo(() => [...createData(75)], []); const columns = React.useMemo( () => [ { canGroupBy: true, Header: 'Age', accessor: 'age', Footer: (info) => { const total = React.useMemo( () => info.rows.reduce((sum, row) => row.values.age + sum, 0), [info.rows] ); return ( Avg: {Math.round((total / info.rows.length) * 100) / 100} ); }, }, { canGroupBy: true, Header: 'Visits', accessor: 'visits', Footer: (info) => { // Only calculate total visits if rows change const total = React.useMemo( () => info.rows.reduce((sum, row) => row.values.visits + sum, 0), [info.rows] ); return Total: {total}; }, }, { Header: 'Status', accessor: 'status', Footer: Status, }, ], [] ); const dataTableProps = useDataTable({ initialData: data, initialColumns: columns, }); return ; }; ``` ### Styling rows and cells See the following two examples on approaches for highlighting rows and cells in DataTable. #### Using the CSS prop This approach uses the `css` prop to style specific rows and cells. Each row and cell in the DataTable has a uniqe class name based on its position (column and/or row number); header cells can be styled as well. ```jsx live-in-view () => { const { data } = utils.useDocDataTable(50, 3); const columns = React.useMemo( () => [ { Header: 'Column 1', accessor: 'col1', }, { Header: 'Column 2', accessor: 'col2', }, { Header: 'Column 3', accessor: 'col3', }, ], [] ); const dataTablePropsPagination = useDataTable({ showPagination: true, initialData: data, initialColumns: columns, }); return ( ); }; ``` #### Using cell function This approach uses the column `Cell` function to highlight particular cells. Note: This approach provides a custom container within each cell and therefore overrides the built-in, alternating background coloring of rows. ```jsx live-in-view () => { const { data } = utils.useDocDataTable(50, 3); const CellContainer = ({ value, highlight }) => { return {value}; }; const rowsToHighlight = [2, 3, 9]; const cellIsHighlighted = ({ page, row }) => { console.log({ page, row }); const rowIndex = page.findIndex((p) => p.id === row.id); const isHighlighted = rowsToHighlight.includes(rowIndex); return isHighlighted; }; const columns = React.useMemo( () => [ { Header: 'Column 1', accessor: 'col1', Cell: ({ value, ...rest }) => { const highlight = cellIsHighlighted(rest); return ; }, }, { Header: 'Column 2', accessor: 'col2', Cell: ({ value, ...rest }) => { const highlight = cellIsHighlighted(rest); return ; }, }, { Header: 'Column 3', accessor: 'col3', Cell: ({ value, ...rest }) => { const highlight = cellIsHighlighted(rest); return ; }, }, ], [] ); const dataTablePropsPagination = useDataTable({ showPagination: true, initialData: data, initialColumns: columns, }); return ( /> ); }; ``` ## Pagination Use the `showPagination` prop to enable default pagination for the data table. Use the `additionalPaginationText` prop to display custom text under the pagination results container. Use the `paginationResultsLabel` prop to change the default 'Results' label. The default value for `showPagination` is `true`. ```jsx live-in-view () => { const { data, columns } = utils.useDocDataTable(500); const dataTablePropsPagination = useDataTable({ showPagination: true, initialData: data, initialColumns: columns, additionalPaginationText: 'Custom Text For Pagination', paginationResultsLabel: 'Custom Results Label', }); return ; }; ``` ### Default page Use the `defaultPage` prop to set the initial page index the data table will load on. The table uses zero-based indexing, so `defaultPage: 2` means the table begins on the third page. If the `defaultPage` is not within the range of total pages, it will reset to the very first page. **Note:** When using the `defaultPage` prop in conjunction with `setData` or `setColumns`, you need to ensure you are passing the second parameter as `true`: `setData(newData, true)`. ```jsx live-in-view () => { const { data, columns } = utils.useDocDataTable(500); const dataTablePropsDefaultPage = useDataTable({ showPagination: true, defaultPage: 2, initialData: data, initialColumns: columns, }); return ( ); }; ``` ### Page size options Use the `pageSizeOptions` prop to pass in various page size options the user can select from. The first option will be the initial page size by default. To change the default page size, pass the `pageSizeDefault` prop to the `useDataTable` hook. ```jsx live-in-view () => { const { data, columns } = utils.useDocDataTable(500); const dataTablePropsTop = useDataTable({ showPagination: true, pageSizeOptions: [6, 8, 10], pageSizeDefault: 8, initialData: data, initialColumns: columns, }); return ; }; ``` ### Hide top pagination Use the `showTopPagination` prop to enable or disable the top pagination components (when `showPagination` is true). The default value is `true`. ```jsx live-in-view () => { const { data, columns } = utils.useDocDataTable(500); const dataTablePropsTop = useDataTable({ showPagination: true, showTopPagination: false, initialData: data, initialColumns: columns, }); return ( ); }; ``` ### Compact bottom pagination Use the `paginationBottomCompact` prop to enable the compact variant of bottom pagination. The compact variant will also trigger if the page size is small enough. ```jsx live-in-view () => { const { data, columns } = utils.useDocDataTable(500); const dataTablePropsCompact = useDataTable({ showPagination: true, showTopPagination: false, initialData: data, initialColumns: columns, paginationBottomCompact: true, }); return ( <> ); }; ``` ### Hide bottom pagination Use the `showBottomPagination` prop to enable or disable the bottom pagination components (when `showPagination` is true). The default value is `true`. ```jsx live-in-view () => { const { data, columns } = utils.useDocDataTable(500); const dataTablePropsBottom = useDataTable({ showPagination: true, showBottomPagination: false, initialData: data, initialColumns: columns, }); return ( ); }; ``` ### Pagination result count override Use the `paginationResultsTotalCount` prop to display a different total count value than the number of items in the table. ```jsx live-in-view () => { const { data, columns } = utils.useDocDataTable(500); const dataTablePropsPagination = useDataTable({ showPagination: true, initialData: data, initialColumns: columns, additionalPaginationText: 'Custom Text For Pagination', paginationResultsTotalCount: 3000, }); return ; }; ``` ### Programmatic page navigation Programmatic page navigation can be accomplished through use of methods contained in the `pagination` property returned through `useDataTable`. Below are examples for navigating forwards, backwards, or to a specific page. ```jsx live-in-view () => { const { data, columns } = utils.useDocDataTable(500); const dataTablePropsPagination = useDataTable({ showPagination: true, initialData: data, initialColumns: columns, }); const handleNextClick = () => { dataTablePropsPagination.pagination.nextPage(); }; const handleBackClick = () => { dataTablePropsPagination.pagination.previousPage(); }; const handleRandomClick = () => { const randomPage = Math.floor( Math.random() * dataTablePropsPagination.pagination.pageCount ) + 1; dataTablePropsPagination.pagination.gotoPage(randomPage); }; return ( <> ); }; ``` ## Server-side pagination Instead of supplying the table's entire dataset at once, you can hook up the table to an API and load the data page-by-page as needed. To use server-side pagination: - Pass in an `apiPaginationCall` function that will call the API and return the relevant page data There are additional props to modify the server-side pagination: `apiQueryOptions`, `manualSortBy`, `customGetRowId` and `disableApiCallOnLoad` - however, these props are not required. ```jsx live-in-view () => { const getMockData = utils.useDataTableApiMock(); const bulkActions = [ { onClick: ({ deleteRows, getSelectedRowIds, clearCache }) => { deleteRows(); const selectedRowIds = getSelectedRowIds(); // Add something to hit the API here with selectedRowIds to update the database if (selectedRowIds.length > 0) { clearCache(); } }, icon: , label: 'Delete Rows', isSeparated: true, }, { onClick: ({ modifyRows, getSelectedRowIds, clearCache }) => { modifyRows({ name: 'Modified Cell' }); const selectedRowIds = getSelectedRowIds(); // Add something to hit the API here with selectedRowIds to update the database if (selectedRowIds.length > 0) { clearCache(); } }, label: 'Modify Cells', }, { onClick: ({ modifyRows, getSelectedRowIds, clearCache }) => { modifyRows({ name: `Modified Name`, sortOrder: `Modified Sort Order`, }); const selectedRowIds = getSelectedRowIds(); // Add something to hit the API here with selectedRowIds to update the database if (selectedRowIds.length > 0) { clearCache(); } }, label: 'Modify Rows', icon: , isSingle: true, }, ]; const individualActions = [ { onClick: ({ deleteRow, row, clearCache }) => { deleteRow(row); clearCache(); }, checkDisabled: (row) => { return row.values.sortOrder % 2 === 0; }, icon: , label: 'Delete Row', isSeparated: true, }, { onClick: ({ modifyRow, row, clearCache }) => { modifyRow(row, { name: 'Modified Cell' }); clearCache(); }, label: 'Modify Cell', }, { onClick: ({ modifyRow, row, clearCache }) => { modifyRow(row, { name: `Modified Name`, sortOrder: `Modified Sort Order`, }); clearCache(); }, label: 'Modify Row', icon: , }, ]; const columns = React.useMemo( () => [ { Header: 'Name', accessor: 'name', }, { Header: 'Sort Order', accessor: 'sortOrder', }, ], [] ); const dataTableProps = useDataTable({ initialColumns: columns, showSelection: true, bulkActions, individualActions, showPagination: true, showColumnVisibilityConfig: true, pageSizeDefault: 5, pageSizeOptions: [5, 10], defaultSelectedRows: { 1: true, }, uniqueStorageId: 'server-side', apiPaginationCall: getMockData, manualSortBy: true, onColumnVisibilityClose: (columns) => console.log('columns', columns, dataTableProps.columnMgmt.allColumns), }); return ( ); }; ``` ### API pagination call Use the `apiPaginationCall` prop to use an API to handle fetching data for the table. `apiPaginationCall` must be a function that takes five parameters, `page`, `pageSize`, `sortBy`, `globalFilter`, and `columnFilters`, and it must return an object with `results` and `count` fields, for the returned data and total number of results respectively. See the example function below. By default this function will be called on page load. To override this default behavior add the `disableApiCallOnLoad` prop and set to `true`. From there you'll need to use [reloadTableData](#triggering-data-refresh) to make the initial call and initiate server-side pagination functionality. ```jsx const apiPaginationCall = (page, pageSize, sortBy, globalFilter, columnFilters) => { // You only need to handle global filtering at the API level like this if you also pass the manualGlobalFilter prop as `true` into useDataTable const globalFilterStr = `&globalFilter=${globalFilter}`; // You only need to handle column filtering at the API level like this if you also pass the manualColumnFilter prop as `true` into useDataTable const columnFiltersStr = `&columnFilters=${JSON.stringify(columnFilters)}`; // You only need to handle sorting at the API level like this if you also pass the manualSortBy prop as `true` into useDataTable const orderByStr = sortBy && sortBy.length > 0 ? `&order_by=${sortBy[0].id}` : ''; const sortDirection = sortBy && sortBy.length > 0 ? `&sort=${sortBy[0].desc ? 'desc' : 'asc'}` : ''; return fetch( `${Your API Endpoint link}?page=${page}&limit=${pageSize}${orderByStr}${sortDirection}${globalFilterStr}${columnFiltersStr}` ) .then((res) => res.json()) .then((res) => { return { results: res.data, // The data returned from the API count: res.total // The total number of results (for the entire dataset, not the current page) }; }); } ```
Other than these requirements, you are free to do whatever API calls, etc. are necessary within the function to return the data. `apiPaginationCall` will be called every time the data for a page will be fetched. When the data for a page has already been cached, `apiPaginationCall` will not be called, as the cached data will be used to minimize unnecessary API calls. For more information about caching and prefetching, see the [API Query Options](#api-query-options) section. ### API query options Use the `apiQueryOptions` prop to specify additional options for the API queries. This prop is an object with three possible properties that can be contained in it: - `onCalled`: a function that is triggered every time a query is called. This function receives no parameters. - `onCompleted`: a function that is triggered every time a query is completed. This function receives one parameter, the response from the query. - `requestPolicy`: pass this prop with the value 'no-cache' to disable the caching and prefetching of data. Otherwise, by default, every time a page is queried, the pages directly before and after it will also be queried to fetch the data before it is needed. Additionally by default, each page will be cached when it is fetched so that going back to a previously visited page will use the cached data rather than calling the API again. - `disablePrefetching`: a boolean that disables prefetching behavior when true. DataTable prefetches data by default to minimize the time end users see the "loading" icon. You may want to disable prefetching if you are loading large amounts of data on your initial page. ```jsx live-in-view () => { const getMockData = utils.useDataTableApiMock(); const columns = React.useMemo( () => [ { Header: 'Name', accessor: 'name', }, { Header: 'Sort Order', accessor: 'sortOrder', }, ], [] ); const dataTableProps = useDataTable({ showSelection: false, initialColumns: columns, showPagination: true, showColumnVisibilityConfig: true, additionalPaginationText: 'No caching here; see Console for onCalled and onCompleted logs', pageSizeOptions: [5, 10], uniqueStorageId: 'apiQueryOptions', apiPaginationCall: getMockData, apiQueryOptions: { onCalled: () => { console.log('onCalled'); }, onCompleted: (response) => { console.log('onCompleted', response); }, requestPolicy: 'no-cache', }, onColumnVisibilityClose: (columns) => console.log('columns', columns, dataTableProps.columnMgmt.allColumns), }); return ; }; ``` ### Manual global filter Use the `manualGlobalFilter` prop to specify whether the table will handle global filtering (when `showGlobalFilter` is `true`), or if the API will handle it. - When `manualGlobalFilter` is `false`, setting a global filter will filter on only the current page. (This will not cause any additional API calls.) - When `manualGlobalFilter` is `true`, setting a global filter will call the API again, which is responsible for returning the filtered data. A `globalFilter` string will be passed to `apiPaginationCall`, which will contain the value of the global filter.
With `manualGlobalFilter` as `true`: ```jsx live-in-view () => { const getMockData = utils.useDataTableApiMock(); const columns = React.useMemo( () => [ { Header: 'Name', accessor: 'name', }, { Header: 'Sort Order', accessor: 'sortOrder', }, ], [] ); const dataTableProps = useDataTable({ showSelection: false, initialColumns: columns, showPagination: true, showColumnVisibilityConfig: true, pageSizeOptions: [5, 10], uniqueStorageId: 'manualGlobalFilter-true', apiPaginationCall: getMockData, showGlobalFilter: true, initialGlobalFilter: '1', manualGlobalFilter: true, onColumnVisibilityClose: (columns) => console.log('columns', columns, dataTableProps.columnMgmt.allColumns), }); return ; }; ```
With `manualGlobalFilter` as `false`: ```jsx live-in-view () => { const getMockData = utils.useDataTableApiMock(); const columns = React.useMemo( () => [ { Header: 'Name', accessor: 'name', }, { Header: 'Sort Order', accessor: 'sortOrder', }, ], [] ); const dataTableProps = useDataTable({ showSelection: false, initialColumns: columns, showPagination: true, showColumnVisibilityConfig: true, pageSizeOptions: [5, 10], uniqueStorageId: 'manualGlobalFilter-false', apiPaginationCall: getMockData, showGlobalFilter: true, initialGlobalFilter: 'Test Datapoint A', onColumnVisibilityClose: (columns) => console.log('columns', columns, dataTableProps.columnMgmt.allColumns), }); return ( ); }; ``` ### Manual column filters Use the `manualColumnFilters` prop to specify whether the table will handle column filtering (when `showFilterDataset` is `true`), or if the API will handle it. - When `manualColumnFilters` is `false`, setting a column filter will filter on only the current page. (This will not cause any additional API calls.) - When `manualColumnFilters` is `true`, setting a column filter will call the API again, which is responsible for returning the filtered data. A `columnFilters` array will be passed to `apiPaginationCall`, which will contain the active filters. The `columnFilters` array will have the format: ```jsx const columnFilters = [ { id: ${columnId1}, // Column ID value: [ { condition: 'contains', // The condition of the filter filterValue: '2' // The value of the filter }, { condition: 'less-equal', // The condition of the filter filterValue: '100' // The value of the filter }, ... // More filters on the same column ] }, { id: ${columnId2}, // Column ID value: [ { condition: 'equals', // The condition of the filter filterValue: 'test' // The value of the filter }, ... // More filters on the same column ] }, ... // More filters on different columns ] ```
With `manualColumnFilters` as `true`: ```jsx live-in-view () => { const getMockData = utils.useDataTableApiMock(); const columns = React.useMemo( () => [ { Header: 'Name', accessor: 'name', }, { Header: 'Sort Order', accessor: 'sortOrder', }, ], [] ); const dataTableProps = useDataTable({ showSelection: false, initialColumns: columns, showPagination: true, showColumnVisibilityConfig: true, pageSizeOptions: [5, 10], uniqueStorageId: 'manualColumnFilters-true', apiPaginationCall: getMockData, showFilterDataset: true, initialFilters: [ { columnId: 'sortOrder', filters: [{ condition: 'greater-equal', filterValue: '10' }], }, ], manualColumnFilters: true, onColumnVisibilityClose: (columns) => console.log('columns', columns, dataTableProps.columnMgmt.allColumns), }); return ( ); }; ```
With `manualColumnFilters` as `false`: ```jsx live-in-view () => { const getMockData = utils.useDataTableApiMock(); const columns = React.useMemo( () => [ { Header: 'Name', accessor: 'name', }, { Header: 'Sort Order', accessor: 'sortOrder', }, ], [] ); const dataTableProps = useDataTable({ showSelection: false, initialColumns: columns, showPagination: true, showColumnVisibilityConfig: true, pageSizeOptions: [5, 10], uniqueStorageId: 'manualColumnFilters-false', apiPaginationCall: getMockData, showFilterDataset: true, initialFilters: [ { columnId: 'sortOrder', filters: [{ condition: 'greater-equal', filterValue: '10' }], }, ], onColumnVisibilityClose: (columns) => console.log('columns', columns, dataTableProps.columnMgmt.allColumns), }); return ( ); }; ``` ### Manual sort by Use the `manualSortBy` prop to specify whether the table will handle column sorting, or if the API will handle it. - When `manualSortBy` is `false`, sorting a column will sort on only the current page. (This will not cause any additional API calls.) - When `manualSortBy` is `true`, sorting a column will call the API again, which is responsible for returning the sorted data. A `sortBy` array will be passed to `apiPaginationCall`, which will contain the IDs of the columns being sorted on, as well as whether the sort order is ascending or descending. The `sortBy` array will have the format: ```jsx const sortBy = [{ id: ${columnId1}, desc: false // ascending order }, { id: ${columnId2}, desc: true, // descending order }, ...] ```
With `manualSortBy` as `true`: ```jsx live-in-view () => { const getMockData = utils.useDataTableApiMock(); const columns = React.useMemo( () => [ { Header: 'Name', accessor: 'name', }, { Header: 'Sort Order', accessor: 'sortOrder', }, ], [] ); const dataTableProps = useDataTable({ showSelection: false, initialColumns: columns, showPagination: true, showColumnVisibilityConfig: true, pageSizeOptions: [5, 10], uniqueStorageId: 'manualSortBy-true', apiPaginationCall: getMockData, manualSortBy: true, onColumnVisibilityClose: (columns) => console.log('columns', columns, dataTableProps.columnMgmt.allColumns), }); return ; }; ```
With `manualSortBy` as `false`: ```jsx live-in-view () => { const getMockData = utils.useDataTableApiMock(); const columns = React.useMemo( () => [ { Header: 'Name', accessor: 'name', }, { Header: 'Sort Order', accessor: 'sortOrder', }, ], [] ); const dataTableProps = useDataTable({ showSelection: false, initialColumns: columns, showPagination: true, showColumnVisibilityConfig: true, pageSizeOptions: [5, 10], uniqueStorageId: 'manualSortBy-false', apiPaginationCall: getMockData, onColumnVisibilityClose: (columns) => console.log('columns', columns, dataTableProps.columnMgmt.allColumns), }); return ; }; ``` ### Custom row IDs Use the `customGetRowId` prop to pass a function that will override how row IDs are set. By default, a row's ID will be equal to its index in the dataset (ex. the third row on the second page of a dataset with 10 rows per page will have an ID of 12). Overriding this function would be useful if are using row selection and want to make a call to your API when users update data in the table. (See the [Bulk Actions](#bulk-actions) section for more details on performing actions on selected data.) The `customGetRowId` function will be called on each row, and will receive three parameters: `row`, `relativeIndex`, and `parent`. Its return value must be the ID for each row. (Make sure each row's ID is unique.) - `row` is the current row, so you can use its fields to form the ID (ex. if each row has an `id` field, you can return `row.id` for the custom row ID). - `relativeIndex` is the row's index relative to the current page, not its absolute index in the overall dataset. (So if the current row is the first row on the tenth page, its `relativeIndex` will be `0`.) - `parent` is the row's parent, if it has one. ```jsx live-in-view () => { const getMockData = utils.useDataTableApiMock(); const columns = React.useMemo( () => [ { Header: 'Name', accessor: 'name', }, { Header: 'Sort Order', accessor: 'sortOrder', }, ], [] ); const dataTableProps = useDataTable({ initialColumns: columns, showSelection: true, showPagination: true, showColumnVisibilityConfig: true, pageSizeOptions: [5, 10], defaultSelectedRows: { 'Test Datapoint A': true, 'Test Datapoint C': true, }, uniqueStorageId: 'customRowId', apiPaginationCall: getMockData, customGetRowId: (row, relativeIndex, parent) => { return row.name; }, onColumnVisibilityClose: (columns) => console.log('columns', columns, dataTableProps.columnMgmt.allColumns), }); return (

        
          Selected Row IDs (Custom):
          {JSON.stringify(dataTableProps.state.selectedRowIds, null, 2)}

); }; ``` ```jsx live-in-view () => { const getMockData = utils.useDataTableApiMock(); const columns = React.useMemo( () => [ { Header: 'Name', accessor: 'name', }, { Header: 'Sort Order', accessor: 'sortOrder', }, ], [] ); const dataTableProps = useDataTable({ showSelection: false, initialColumns: columns, showSelection: true, showPagination: true, showColumnVisibilityConfig: true, pageSizeOptions: [5, 10], defaultSelectedRows: { 0: true, 2: true, }, uniqueStorageId: 'defaultRowId', apiPaginationCall: getMockData, onColumnVisibilityClose: (columns) => console.log('columns', columns, dataTableProps.columnMgmt.allColumns), }); return (

        
          Selected Row IDs (Default):
          {JSON.stringify(dataTableProps.state.selectedRowIds, null, 2)}

); }; ``` ### Triggering data refresh When using server-side pagination, you can re-trigger the apiPaginationCall function by calling the `reloadTableData` method returned from the `useDataTable` hook. This should also be used to trigger the initial call to apiPaginationCall whenever `disableApiCallOnLoad` is applied, as seen in the [Disable On Load](#disable-on-load) example below. When `reloadTableData` is called, it will utilize the current page, sort and filter state settings. ```jsx live-in-view () => { const getMockData = utils.useDataTableApiMock(); const columns = React.useMemo( () => [ { Header: 'Name', accessor: 'name', }, { Header: 'Sort Order', accessor: 'sortOrder', }, ], [] ); const tableState = useDataTable({ showSelection: false, initialColumns: columns, showPagination: true, apiPaginationCall: getMockData, apiQueryOptions: { onCalled: () => { console.log('onCalled'); }, onCompleted: (response) => { console.log('onCompleted', response); }, requestPolicy: 'no-cache', }, }); const handleRefreshClick = () => { tableState.reloadTableData(); }; return ( ); }; ``` #### Disable on load ```jsx live-in-view () => { const getMockData = utils.useDataTableApiMock(); const columns = React.useMemo( () => [ { Header: 'Name', accessor: 'name', }, { Header: 'Sort Order', accessor: 'sortOrder', }, ], [] ); const [disabledState, setDisabledState] = useState(true); const tableState = useDataTable({ showSelection: false, initialColumns: columns, showPagination: true, apiPaginationCall: getMockData, apiQueryOptions: { onCalled: () => { console.log('onCalled'); }, onCompleted: (response) => { console.log('onCompleted', response); }, requestPolicy: 'no-cache', }, disableApiCallOnLoad: true, }); const handleLoadOnClick = () => { tableState.reloadTableData(); }; return ( ); }; ``` ## Custom messaging ### No data message To override the default no data message use the `noDataMessage` prop to pass a custom message into the `useDataTable` hook. ```jsx live-in-view () => { const { data } = utils.useDocDataTable(5); const columns = React.useMemo( () => [ { Header: 'Column 1', accessor: 'col1', canToggleVisibilty: false, }, { Header: 'Column 2', accessor: 'col2', canToggleVisibilty: false, }, { Header: 'Column 3', accessor: 'col3', canToggleVisibilty: false, }, ], [] ); const dataTableProps = useDataTable({ initialData: [], initialColumns: columns, noDataMessage: 'Custom No Data Message', }); return ; }; ``` ### Error message Use the `errorMessage` prop to pass a custom error message into the `useDataTable` hook. If `errorMessage` contains a value it will display and override any present data. If no `errorMessage` is added a default message will display whenever `apiPaginationCall` is used and an error occurs during the api call. ```jsx live-in-view () => { const getMockData = utils.useDataTableApiMock({ throwError: true }); const [errorMessage, setErrorMessage] = useState(null); const columns = React.useMemo( () => [ { Header: 'Name', accessor: 'name', }, { Header: 'Sort Order', accessor: 'sortOrder', }, ], [] ); const dataTableProps = useDataTable({ initialColumns: columns, showPagination: true, errorMessage, apiPaginationCall: getMockData, apiQueryOptions: { onCalled: () => { console.log('onCalled'); }, onCompleted: (response) => { console.log('onCompleted', response); }, onError: (err) => { console.log('onError', err); setErrorMessage(err); }, }, }); return ; }; ``` ## Data test ID To include a `data-testid` attribute within the included DataTable features like selection, expansion rows, etc. you must pass the `data-testid` prop into the `useDataTable` hook as well as the `DataTable` component itself. For reference, please view the code in the example below. For more information on usage of the `data-testid` attribute, visit the [Component Testing page](/web/developers/testing/component-testing/#data-testid). ```jsx live-in-view () => { const { columns } = utils.useDocDataTable(1000); const data = [ { col1: `Col 1/Row 1`, col2: `Col 2/Row 1`, expandedByDefault: true, }, { col1: `Col 1/Row 2`, col2: `Col 2/Row 2`, }, { col1: `Col 1/Row 3`, col2: `Col 2/Row 3`, }, { col1: `Col 1/Row 4`, col2: `Col 2/Row 4`, }, ]; const renderRowSubComponent = React.useCallback((row) => { return (

        {JSON.stringify({ values: row.values }, null, 2)}

); }, []); const dataTablePropsPagination = useDataTable({ renderSubComponent: renderRowSubComponent, initialData: data, initialColumns: columns, 'data-testid': 'expansion-test-id', }); return ( ); }; ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` In addition to the above classes, DataTable also uses the classes from the [Table](/web/ui/Table?tab=integration) component. The data table headers accurately describe the data contained in the rows and columns. If the data table has a labels it should be clear and concise. Resources W3C WAI-ARIA Authoring Practices Table Design Pattern covers the usage of ARIA names, state and roles, as well as the expected keyboard interactions. W3C Tutorial - Table Concepts covers the usage of various tables, headers, and captions. IBM Accessibility Requirements: - 1.3.1 Info and Relationships (WCAG Success Criteria 1.3.1) - 1.3.2 Meaningful Sequence (WCAG Success Criteria 1.3.2) - 2.1.1 Keyboard (WCAG Success Criteria 2.1.1) - 2.4.3 Focus Order (WCAG Success Criteria 2.4.3) - 2.4.6 Headings and Labels (WCAG Success Criteria 2.4.6) - 2.4.7 Focus Visible (WCAG Success Criteria 2.4.7) - 4.1.2 Name, Role, Value (WCAG Success Criteria 4.1.2) Turn a column into a row header by passing the `isRowHeader: true` prop to an individual column.

Reduced Motion

Animations and transitions that have been changed when a user has `prefers-reduced-motion` set to `reduced`: - Table Settings `Drawer` has the transition removed --- id: date-input-v2 category: Forms title: V2DateInput description: Capture date input from user. design: https://www.figma.com/design/a8XbEI7AmNb94mOBgYUB7y/v1.72.0-Web-Abyss-Global%E2%80%A8Component-Library?node-id=4543-169 subDirectory: DateInput/v2 sourceIsTS: true --- ```jsx render ``` ```jsx import { V2DateInput } from '@uhg-abyss/web/ui/DateInput'; ``` ```jsx sandbox { component: 'V2DateInput', inputs: [ { prop: 'label', type: 'string', }, { prop: 'subText', type: 'string', }, { prop: 'errorMessage', type: 'string', }, { prop: 'successMessage', type: 'string', }, { prop: 'dateFormat', type: 'string', defaultValue: 'MM/DD/YYYY', }, { prop: 'hideLabel', type: 'boolean', }, { prop: 'isClearable', type: 'boolean', }, { prop: 'isDisabled', type: 'boolean', }, { prop: 'highlighted', type: 'boolean', }, { prop: 'matchAnchorWidth', type: 'boolean', defaultValue: true, }, ] } () => { const [value, setValue] = useState(); return ( setValue(e.target.value)} /> ); }; ``` ## Day.js `V2DateInput` relies on the Day.js library to handle date operations. Several inputs to the `V2DateInput` are `Dayjs` objects. Abyss includes a [Day.js tool](/web/tools/dayjs), which includes a number of preset Day.js plugins, but you can also install Day.js separately. ```jsx import { dayjs } from '@uhg-abyss/web/tools/dayjs'; ``` ## Variants ### Input with calendar The default variant for `V2DateInput` is an input field with a button to open a calendar. ```jsx live () => { const form = useFormV2({ defaultValues: { 'input-with-calendar': dayjs().format('MM/DD/YYYY'), }, }); return ( ); }; ``` ### Input only Use the `inputOnly` prop when the date can be easily entered without a calendar; for example, when entering a birthday. ```jsx live () => { const form = useFormV2({ defaultValues: { 'input-only': dayjs().format('MM/DD/YYYY'), }, }); return ( ), description: 'Schedule appointment', }} /> ); }; ``` ## useFormV2 (recommended) ```jsx render ``` ```jsx render ``` ```jsx live () => { const form = useFormV2({ defaultValues: { dateForm: dayjs().format('MM/DD/YYYY'), }, }); const onSubmit = (data) => { console.log('data', data); }; return ( Submit ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [value, setValue] = useState(dayjs().format('MM/DD/YYYY')); const onSubmit = () => { console.log('value', value); }; return ( { console.log('onChange', e.target.value); setValue(e.target.value); }} isClearable /> Submit ); }; ``` ## Display properties ### Label Use the `label` prop to display a label above the input. To hide the input label, set `hideLabel` to `true`. Use `isRequired` and `isOptional` for further customization. **Note:** If using `useForm`, do not use `isRequired`. The same functionality can be achieved with `required: true` in `validators`. ```jsx live () => { return ( ); }; ``` ### Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip-v2) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip-v2) or a [Popover](/web/ui/popover-v2). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip-v2/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live () => { const form = useFormV2(); return ( } model="helper-custom" validators={{ required: true }} /> ); }; ``` ### Subtext Use the `subText` prop to display helpful information related to the input field. The prop accepts either a string or an object of the form: ```ts { text: string; position: 'above' | 'below'; } ``` The `position` property determines where the subtext will be displayed in relation to the input field. The default value is `'below'`. ```jsx live () => { const form = useFormV2(); return ( ); }; ``` ### Date format Use the `dateFormat` prop to specify the format of the date displayed in the input field. The value given will also change the field's formatting hint and input mask. The default format is `'MM/DD/YYYY'`. **Note**: The format must be compatible with the Day.js library. Due to the input mask used, `V2DateInput` does not support any substrings that would require non-numeric characters. Of the available formatting substrings, only the following are supported: | Format | Description | | :------- | :------------------------------------ | | `'YY'` | Two-digit year | | `'YYYY'` | Four-digit year | | `'M'` | The month, beginning at 1 | | `'MM'` | The month, 2-digits | | `'D'` | The day of the month | | `'DD'` | The day of the month, 2-digits | | `'d'` | The day of the week, with Sunday as 0 |
**Note**: The initial/default value, provided either through `useFormV2` or `useState`, must also be in the specified date format. ```jsx live () => { const defaultDateFormat = 'MM/DD/YYYY'; const customDateFormat = 'DD.MM.YYYY'; const form = useFormV2({ defaultValues: { 'default-date-format': dayjs().format(defaultDateFormat), 'custom-date-format': dayjs().format(customDateFormat), }, }); const onSubmit = (data) => { console.log('data', data); }; return ( Submit ); }; ``` ### Hide placeholder By default, the input will container a formatting placeholder that matches the specified [date format](#date-format). Use the `hidePlaceholder` prop to control the placeholder's visibility. The default value is `false`. **Note**: The formatting mask is unaffected by this prop. The placeholder is only visible if there is no text in the input. ```jsx live () => { const form = useFormV2(); return ( ); }; ``` ### Width Use the `width` prop to set the width of the input field. ```jsx live () => { const form = useFormV2(); return ( ); }; ``` ### Left element Use the `inputLeftElement` prop to add an element inside of the text input field. The recommended usage is for inserting icons. The prop accepts an object with the following properties: - `element`: The element to be displayed inside the input field. - `description`: An optional string that describes the purpose of the element for screen readers. These are considered decorative and do not need to be exposed to screen readers. That said, please note that icons should _not_ provide any information that is not also conveyed in a screen-readable way. For example, an exclamation mark (!) icon to indicate errors needs to be accompanied by `aria-invalid`. If the icon is used to convey additional information, use the `inputLeftElement.description` prop to provide a description for screen readers. **Note:** The recommended usage is when using the `inputOnly` prop. ```jsx live () => { const form = useFormV2({ defaultValues: { 'left-element': dayjs().format('MM/DD/YYYY'), }, }); return ( ), description: 'Schedule appointment', }} /> ); }; ``` ### Match anchor width By default, the calendar will match the width of the input field. To disable this behavior, set the `matchAnchorWidth` prop to `false`. The calendar will then take up the minimum width required. **Note**: If the input field width is less than the minimum width of the calendar (340px), the value of `matchAnchorWidth` will be ignored to prevent the calendar from overflowing the container. ```jsx live () => { const form = useFormV2(); return ( ); }; ``` ## Validation ### Validators (useFormV2) ```jsx render ``` Use the `validators` prop to set validation rules for the field when using `useFormV2`. See the examples below for implementation on various types of validation. **Note:** The default error message when `required` is `true` is minimally acceptable for accessibility. It is highly recommended to customize it to be more specific to the use of the field and form. ```jsx live () => { const form = useFormV2(); return ( { if (!value) { return 'Select a date'; } const date = dayjs(value, 'MM/DD/YYYY', true); if (!date.isValid()) { return 'Provide a valid date'; } return date.date() % 2 === 0 || 'Date must be even'; }, }, }} /> Submit ); }; ``` ### Error message (useState) ```jsx render ``` Use the `errorMessage` prop to display a custom error message below the input field when using `useState`. ```jsx live () => { const [value, setValue] = useState(dayjs().format('MM/DD/YYYY')); return ( setValue(e.target.value)} errorMessage="Custom error message" /> ); }; ``` ### Success message ```jsx render ``` Use the `successMessage` prop to display a custom success message below the input field. To provide a single success message across all form input components using `useFormV2`/`V2FormProvider`, you can provide `successMessage` to `V2FormProvider` as shown [here](/web/ui/form-provider-v2#successmessage). ```jsx live () => { const form = useFormV2(); const onSubmit = (data) => { console.log(data); }; return ( { const date = dayjs(value, 'MM/DD/YYYY', true); if (!date.isValid()) { return 'Provide a valid date'; } return date.day() === 1 || 'Date must be a Monday'; }, }, }} /> Submit ); }; ``` ```jsx live () => { const inputRef = useRef(null); const [value, setValue] = useState(''); const [isSubmitted, setIsSubmitted] = useState(false); const [errorMessage, setErrorMessage] = useState(''); const [successMessage, setSuccessMessage] = useState(''); const validateDate = () => { if (!value) { setErrorMessage('Select a date'); setSuccessMessage(''); inputRef.current.focus(); return; } const parsedValue = dayjs(value, 'MM/DD/YYYY', true); if (!parsedValue.isValid()) { setErrorMessage('Provide a valid date'); setSuccessMessage(''); inputRef.current.focus(); } else if (parsedValue.day() !== 1) { setErrorMessage('Date must be a Monday'); setSuccessMessage(''); inputRef.current.focus(); } else { setErrorMessage(''); setSuccessMessage('Date is valid!'); } }; useEffect(() => { if (isSubmitted) { validateDate(); } }, [value]); const onSubmit = (e) => { e.preventDefault(); validateDate(); setIsSubmitted(true); }; return ( setValue(e.target.value)} ref={inputRef} successMessage={successMessage} errorMessage={errorMessage} /> Submit ); }; ``` ### Highlighted ```jsx render ``` Use the `highlighted` prop to enable a distinct background color when fields are required. To supply this across all form input components using `useFormV2`/`V2FormProvider` you can provide `highlighted` to `V2FormProvider` as shown [here](/web/ui/form-provider-v2#highlighted). ```jsx live () => { const form = useFormV2(); return ( ); }; ``` ```jsx live () => { const [value, setValue] = useState(''); return ( setValue(e.target.value)} isRequired highlighted /> ); }; ``` ### Minimum and maximum dates Use the `minDate` and `maxDate` props to only allow dates within a given range to be selected in the calendar. Both props accept a `Dayjs` object. These values are inclusive endpoints, meaning that the date(s) provided can be selected. Learn more about these values in the [V2Calendar documentation](/web/ui/calendar-V2#minimum-and-maximum-dates). In the example below, only the dates from one month before today's date to one month after can be selected. **Note**: The input field will still allow users to enter dates outside of the defined `minDate` and `maxDate` values, so manual validation is required. ```jsx live () => { const form = useFormV2(); const minDate = dayjs().subtract(1, 'month'); const maxDate = dayjs().add(1, 'month'); const message = `Select a date between ${minDate.format( 'MM/DD/YYYY' )} and ${maxDate.format('MM/DD/YYYY')}`; const onSubmit = (data) => { console.log('data', data); }; return ( { const date = dayjs(value, 'MM/DD/YYYY', true); if (!date.isValid()) { return 'Provide a valid date'; } return ( (date.isSameOrAfter(minDate) && date.isSameOrBefore(maxDate)) || message ); }, }, }} /> Submit ); }; ``` ### Exclude dates Use the `excludeDate` prop to prevent certain dates from being selected in the calendar. `excludeDate` accepts a predicate function and checks each date in the current month against it. If the function returns `true`, the matching date will be disabled. In the example below, the `excludeDate` function disables all Sundays and Saturdays. **Note**: The input field will still allow users to enter dates that are excluded, so manual validation is required. ```jsx live () => { const form = useFormV2(); const message = 'Enter weekdays only'; const onSubmit = (data) => { console.log('data', data); }; return ( { return date.day() === 0 || date.day() === 6; }} validators={{ validate: { isValid: (value) => { const date = dayjs(value, 'MM/DD/YYYY', true); if (!date.isValid()) { return 'Provide a valid date'; } return (date.day() !== 0 && date.day() !== 6) || message; }, }, }} /> Submit ); }; ``` ### Validation below menu ```jsx render ``` Set the `validationBelowMenu` prop to `true` to relocate the error and success message validation to below the menu, when open. The default is `false` and the validation message will always remain displayed below the selection container, even when the calendar is open. ```jsx live-in-view () => { const [value, setValue] = useState(); return ( setValue(e.target.value)} isClearable isRequired errorMessage="Select a date" validationBelowMenu /> ); }; ``` ## Interactivity ### Clearable Set the `isClearable` prop to `true` to display a clear button in the input field. The optional `onClear` callback prop can be used to trigger additional actions when the clear button is clicked. ```jsx live () => { const form = useFormV2({ defaultValues: { clearable: dayjs().format('MM/DD/YYYY'), }, }); return ( console.log('input cleared')} /> ); }; ``` ### Disabled Set the `isDisabled` prop to `true` to disable the input field, preventing user interaction. The input will still display the current value, but users cannot change it. ```jsx live () => { const form = useFormV2({ defaultValues: { disabled: dayjs().format('MM/DD/YYYY'), }, }); return ( ); }; ``` ### Enable outside scroll Set the `enableOutsideScroll` prop to `true` to allow the page to be scrolled while the calendar is open. The default value is `false`. ```jsx live () => { const form = useFormV2({ defaultValues: { outsideScroll: dayjs().format('MM/DD/YYYY'), }, }); return ( ); }; ``` ### Confirm selection By default, the clicking on a date in the calendar will set that date as the selected date and close the calendar. By setting the `confirmSelection` prop to `true`, the calendar will display "Apply" and "Cancel" buttons and the user will have to press the "Apply" button to confirm the selection and close the calendar. Use the `onApply` and `onCancel` props to add extra behavior to execute when the "Apply" and "Cancel" buttons are clicked, respectively. `onApply` will receive the selected date as a `Dayjs` object. ```jsx live () => { const form = useFormV2({ defaultValues: { dateForm: dayjs().format('MM/DD/YYYY'), }, }); const onSubmit = (data) => { console.log('data', data); }; return ( { console.log('Applied date:', selectedDate.format('MM/DD/YYYY')); }} onCancel={() => { console.log('Selection cancelled'); }} /> Submit ); }; ``` ## Responsiveness On screens less than 360px wide, the calendar will be placed in a full-screen takeover instead of a popup. Resize the window and open the calendar to see the change! ```jsx live () => { const form = useFormV2({ defaultValues: { dateForm: dayjs().format('MM/DD/YYYY'), }, }); const onSubmit = (data) => { console.log('data', data); }; return ( Submit ); }; ``` ```jsx render ``` ```jsx render ``` Adheres to the Date Picker Dialog WAI-ARIA design pattern. For calendar accessibility information, see: V2Calendar Accessibility documentation. ```jsx live () => { const form = useFormV2(); const minDate = dayjs().subtract(0, 'month'); const maxDate = dayjs().add(2, 'month'); const message = `Select weekday from ${minDate.format( 'MM/DD/YYYY' )} to ${maxDate.format('MM/DD/YYYY')}`; const onSubmit = (data) => { console.log('data', data); }; return ( } model="helper-custom" excludeDate={(date) => { return date.day() === 0 || date.day() === 6; }} validators={{ required: true, validate: { isValid: (value) => { const date = dayjs(value, 'MM/DD/YYYY', true); if (!date.isValid()) { return 'Select a weekday in the next two months'; } if (date.day() == 0 || date.day() == 6) { return 'Not a weekday'; } return ( (date.isSameOrAfter(minDate) && date.isSameOrBefore(maxDate)) || 'Date is not within next two months' ); }, }, }} /> Select ); }; ```

Component Tokens

**Note:** Click on the token row to copy the token to your clipboard. ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` --- id: date-input category: Forms title: DateInput description: Capture date input from user. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=58425-7012 --- ```jsx import { DateInput } from '@uhg-abyss/web/ui/DateInput'; ``` ```jsx sandbox { component: 'DateInput', inputs: [ { prop: 'placeholder', type: 'string', }, { prop: 'subText', type: 'string', }, { prop: 'errorMessage', type: 'string', }, { prop: 'hideLabel', type: 'boolean', }, { prop: 'isDisabled', type: 'boolean', }, { prop: 'highlighted', type: 'boolean', }, ] } () => { const [value, setValue] = useState('11/01/2023'); return ( ); }; ``` ## useForm (recommended) Using the `useForm` hook for handling TextInput lets the DOM handle form data. ```jsx live () => { const form = useForm({ defaultValues: { 'test-date': '01/01/2022', }, }); const onSubmit = (data) => { console.log('data', data); }; return ( ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [value, setValue] = useState('01/10/2022'); console.log('useState Value', value); return ( setValue('')} /> ); }; ``` ## Min/max date Use the `minimumDate` and `maximumDate` props to set the min and max dates in the Calendar dropdown. **Note:** The input fields will still allow users to enter dates outside of the defined `minimumDate` and `maximumDate` values, so you will need to provide validation. See the example below for guidance on implementation. For usage of dayjs please visit [here](https://abyss.uhc.com/web/tools/dayjs/). ```jsx live () => { const form = useForm(); const minDateString = '01/05/2021'; const maxDateString = '02/05/2021'; const minDateObject = dayjs(minDateString); const maxDateObject = dayjs(maxDateString); const message = `Select a date within ${minDateString} to ${maxDateString}`; const onSubmit = (data) => { console.log('data', data); }; return ( { const dateObject = dayjs(v); return ( (dateObject.isSameOrAfter(minDateObject) && dateObject.isSameOrBefore(maxDateObject)) || message ); }, }, }} /> ); }; ``` ## Excluded dates To exclude dates use the `excludeDates` prop. Set a function that receives date as an argument and returns true if date should be disabled. For example, to disable weekends, check if the day is 0 or 6. **Note:** The input fields will still allow users to enter dates outside of the defined `excludeDates` value, so you will need to provide validation. See the example below for guidance on implementation. For usage of dayjs please visit [here](https://abyss.uhc.com/web/tools/dayjs/). ```jsx live () => { const form = useForm(); const message = 'Enter week days only'; const onSubmit = (data) => { console.log('data', data); }; return ( { return date.getDay() === 0 || date.getDay() === 6; }} descriptorsDisplay="column" subText={message} validators={{ validate: { isValid: (v) => { return ( (dayjs(v).get('day') != 0 && dayjs(v).get('day') != 6) || message ); }, }, }} /> ); }; ``` ## Starting/ending year Use the `startingYear` and `endingYear` props to set the min and max years in the Calendar dropdown. **Note:** The input fields will still allow users to enter dates outside the defined `startingYear` and `endingYear` values, so you will need to provide validation. See the example below for guidance on implementation. For usage of dayjs please visit [here](https://abyss.uhc.com/web/tools/dayjs/). ```jsx live () => { const form = useForm(); const startingYear = 1999; const endingYear = 2021; const message = `Select a date within the years ${startingYear} to ${endingYear}`; const onSubmit = (data) => { console.log('data', data); }; return ( { const dateObject = dayjs(v); return ( (dateObject.isSameOrAfter(dayjs(`1/1/${startingYear}`)) && dateObject.isSameOrBefore(dayjs(`12/31/${endingYear}`))) || message ); }, }, }} /> ); }; ``` ## Add elements inside input Use the `inputLeftElement` and `inputRightElement` props to add elements to the inside of the date input field. The recommended usage is for inserting icons. These are considered decorative and do not need to be exposed to screen readers. That said, please note that icons should _not_ provide any information that is not also conveyed in a screen-readable way. For example, an (!) icon to indicate errors needs to be accompanied by `aria-invalid`. If icons are used to convey additional information, use the `inputLeftElementDescription` and `inputRightElementDescription` props to provide a description for screen readers. See the [Validation](#validation) section below for an example on how to incorporate with validation and display error/success states with icons. ```jsx live () => { const form = useForm(); return ( } inputRightElement={ } inputLeftElementDescription="Clipboard Icon" inputRightElementDescription="Checkmark Icon" /> ); }; ``` ## Placeholder Use the `placeholder` prop to give users a short description in the input field before they enter a value. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( ); }; ``` ## Subtext Use the `subText` prop to display helpful text below the date input field. By default it displays `Date Format: mm/dd/yyyy`. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( ); }; ``` ## Error message Use the `errorMessage` prop to display a custom error message below the date input field. **Note:** The errorMessage prop does not work with useForm and is only applicable within our form input components when useState is being utilized. See the [useForm Docs](/web/hooks/use-form#set-error) for example use cases with useForm. ```jsx live () => { const [value, setValue] = useState(null); return ( ); }; ``` ## Descriptors display Use the `descriptorsDisplay` prop to set the orientation of the error message and subtext descriptor content. Available variants include 'column' and 'row'. The default is set to 'row'. Use the [FormProvider](/web/ui/form-provider#descriptors-display) and `descriptorsDisplay` to set the descriptors orientation across an entire form. ```jsx live () => { const [value, setValue] = useState(null); return ( ); }; ``` ## Label Use the `label` prop to display a label above the input. To hide the input label set `hideLabel` to `true`. ```jsx live () => { const form = useForm(); return ( ); }; ``` ## Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip) or a [Popover](/web/ui/popover). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live () => { const form = useForm(); return ( } model="helper-custom" validators={{ required: true }} /> ); }; ``` ## Disabled Set the `isDisabled` prop to `true` to disable the input field so users cannot enter a value. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( ); }; ``` ## Validation Use the `validators` prop to set rules for the field to be valid. ```jsx live () => { const form = useForm(); const { errors, isSubmitted, isSubmitSuccessful } = form.formState; const getIconProps = useCallback( (model) => { if (!isSubmitted) return null; let iconProps = {}; if (!!errors[model]) { iconProps = { icon: 'error', color: '$error1', size: '18px' }; } if (isSubmitSuccessful) { iconProps = { icon: 'check', color: '$success1', size: '18px' }; } return { inputRightElement: }; }, [isSubmitted, isSubmitSuccessful] ); return ( { return ( dayjs(v, 'MM/DD/YYYY').isBefore(dayjs('01/01/2023')) || 'Should be before 01/01/2023' ); }, isAfter: (v) => { return ( dayjs(v, 'MM/DD/YYYY').isAfter(dayjs('01/01/2021')) || 'Should be after 01/01/2021' ); }, }, }} /> ); }; ``` ## Highlighted Use the `highlighted` prop to enable the background color for the input. You can use `FormProvider` and `highlighted` to enable the color to appear if validation is required. ```jsx live () => { const [value, setValue] = useState(); return ( ); }; ``` ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( ); }; ``` ## Width Use the `width` prop to set the width of the input field. ```jsx live () => { const form = useForm(); return ( ); }; ``` ## Enable outside scroll Set the `enableOutsideScroll`prop to`true` to enable scroll outside of the date input component while the calendar is open. Default is set to `false`. ```jsx live () => { const [value, setValue] = useState('01/01/2022'); return ( ); }; ``` ## Clearable Use the `isClearable` prop to include a clearable button for DateInput. By default, this is set to false. Note that if you are using `useState`, you will need to pass the `onClear` prop as well to handle clearing the data when the clear button is pressed. ```jsx live () => { const form = useForm({ defaultValues: { 'test-date': '01/01/2022', }, }); return ( ); }; ``` ```jsx live () => { const [value, setValue] = useState('01/10/2022'); return ( setValue('')} /> ); }; ``` ## Open position Use the `openPosition` prop to set where the calendar should open in relation to the date input field. By default, it will open above or below the input based on the available space. To force a fixed position, set `openPosition` to `top` or `bottom`. It is recommended to use `enableOutsideScroll` as well so that users can adjust the position of the calendar on their screen after opening. **Note:** If the calendar is opened to a position where there is not enough screen space available to accommodate the calendar, it will shift the entire component into view. ```jsx live () => { const [value, setValue] = useState('01/10/2022'); return ( ); }; ``` ```jsx render ``` ```jsx render ``` The example below includes a date input field and a button that opens a date picker that implements the dialog design pattern. The dialog contains a calendar that uses the grid pattern to present buttons that enable the user to choose a day from the calendar. Choosing a date from the calendar closes the dialog and populates the date input field. When the dialog is opened, if the input field is empty, or does not contain a valid date, then the current date is focused in the calendar. Otherwise, the focus is placed on the day in the calendar that matches the value of the date input field. Adheres to the Date Picker Dialog WAI-ARIA design pattern. ```jsx live () => { const form = useForm({ defaultValues: { 'test-date': '01/01/2022', }, }); return ( ); }; ``` ```jsx render

``` ```jsx render ``` ```jsx render ``` ```jsx render ``` --- id: date-input-range category: Forms title: DateInputRange description: Capture date input from user. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=58425-10048 --- ```jsx import { DateInputRange } from '@uhg-abyss/web/ui/DateInputRange'; ``` ```jsx sandbox { component: 'DateInputRange', inputs: [ { prop: 'startDateLabel', type: 'string', }, { prop: 'endDateLabel', type: 'string', }, { prop: 'width', type: 'string', }, { prop: 'isDisabled', type: 'boolean', }, { prop: 'highlighted', type: 'boolean', defaultValue: false, }, ] } () => { const [values, setValues] = useState({ from: '07/11/2022', to: '07/15/2022' }); return ( ); }; ``` ## useForm (recommended) Using the `useForm` hook for handling TextInput lets the DOM handle form data. ```jsx live () => { const form = useForm({ defaultValues: { 'test-form-date': { from: '06/04/2022', to: '06/30/2022' }, }, }); const onSubmit = (data) => { console.log('data', data); }; return ( ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [values, setValues] = useState({ from: '01/01/2022', to: '06/20/2022', }); console.log('useState values', values); return ; }; ``` ## Min/max date Use the `minimumDate` and `maximumDate` props to set the min and max dates in the Calendar dropdown. **Note:** The input fields will still allow users to enter dates outside of the defined `minimumDate` and `maximumDate` values, so you will need to provide validation. See the example below for guidance on implementation. For usage of dayjs please visit [here](https://abyss.uhc.com/web/tools/dayjs/). ```jsx live () => { const form = useForm(); const minDateString = '01/01/2021'; const maxDateString = '12/31/2022'; const minDateObject = dayjs(minDateString); const maxDateObject = dayjs(maxDateString); const validationMessage = `Select a date within ${minDateString} to ${maxDateString}`; const onSubmit = (data) => { console.log('data', data); }; return ( { const toDateObject = dayjs(v.to); const fromDateObject = dayjs(v.from); return ( (toDateObject.isSameOrAfter(minDateObject) && toDateObject.isSameOrBefore(maxDateObject) && fromDateObject.isSameOrAfter(minDateObject) && fromDateObject.isSameOrBefore(maxDateObject)) || validationMessage ); }, isStartDateAfterEndDate: (v) => { const toDateObject = dayjs(v.to); const fromDateObject = dayjs(v.from); return ( fromDateObject.isSameOrBefore(toDateObject) || 'Start date should be less than or same as end date' ); }, }, }} /> ); }; ``` ## Excluded dates To exclude dates use the `excludeDate` prop. Set a function that receives date as an argument and returns true if date should be disabled. For example, to disable weekends, check if the day is 0 or 6. **Note:** The input fields will still allow users to enter dates outside of the defined `excludeDate` value, so you will need to provide validation. See the example below for guidance on implementation. For usage of dayjs please visit [here](https://abyss.uhc.com/web/tools/dayjs/). ```jsx live () => { const form = useForm(); const validationMessage = 'Enter week days only'; const onSubmit = (data) => { console.log('data', data); }; return ( { return date.getDay() === 0 || date.getDay() === 6; }} subText={validationMessage} descriptorsDisplay="column" validators={{ validate: { isValid: (v) => { return ( (dayjs(v.to, 'MM/DD/YYYY').get('day') != 0 && dayjs(v.to, 'MM/DD/YYYY').get('day') != 6 && dayjs(v.from, 'MM/DD/YYYY').get('day') != 0 && dayjs(v.from, 'MM/DD/YYYY').get('day') != 6) || validationMessage ); }, isStartDateAfterEndDate: (v) => { const toDateObject = dayjs(v.to); const fromDateObject = dayjs(v.from); return ( fromDateObject.isSameOrBefore(toDateObject) || 'Start date should be less than or same as end date' ); }, }, }} /> ); }; ``` ## Starting/ending year Use the `startingYear` and `endingYear` props to set the min and max years in the Calendar dropdown. **Note:** The input fields will still allow users to enter dates outside the defined `startingYear` and `endingYear` values, so you will need to provide validation prop. See the example below for guidance on implementation. For usage of dayjs please visit [here](https://abyss.uhc.com/web/tools/dayjs/). ```jsx live () => { const form = useForm(); const startingYear = 2021; const endingYear = 2023; const validationMessage = `Select a date within the years ${startingYear} to ${endingYear}`; const onSubmit = (data) => { console.log('data', data); }; return ( { const toDateObject = dayjs(v.to); const fromDateObject = dayjs(v.from); return ( (toDateObject.isSameOrAfter(dayjs(`1/1/${startingYear}`)) && toDateObject.isSameOrBefore(dayjs(`12/31/${endingYear}`)) && fromDateObject.isSameOrAfter(dayjs(`1/1/${startingYear}`)) && fromDateObject.isSameOrBefore( dayjs(`12/31/${endingYear}`) )) || validationMessage ); }, isStartDateAfterEndDate: (v) => { const toDateObject = dayjs(v.to); const fromDateObject = dayjs(v.from); return ( fromDateObject.isSameOrBefore(toDateObject) || 'Start date should be less than or same as end date' ); }, }, }} /> ); }; ``` ## Add elements inside input Use the `inputLeftElement` and `inputRightElement` props to add elements to the inside of the start and end date input fields. Within each prop pass in a `start` and/or `end` property with the desired element node. The recommended usage is for inserting icons. See the [Validation](#validation) section below for an example on how to incorporate with validation and display error/success states with icons. **Note:**
It is suggested to NOT use icons for additional information that are not conveyed in other ways. For example, an (!) icon to indicate errors would be covered by aria-invalid settings. If icons are used to convey additional information, it's up to the user themselves to add off-screen content to aria-describedby. ```jsx live () => { const form = useForm(); return ( , end: , }} inputRightElement={{ start: , end: , }} /> ); }; ``` ## Placeholder Use the `startDatePlaceholder` and `endDatePlaceholder` prop to give users a short description in the input field before they enter a value. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( ); }; ``` ## Subtext Use the `subtext` prop to display helpful text below the date range input fields. By default it displays `Date Format: mm/dd/yyyy`. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( ); }; ``` ## Error message Use the `errorMessage` prop to display a custom error message below the date range input fields. To have specific errors under the start and end date inputs, instead use `startDateErrorMessage` and `endDateErrorMessage`. This can be useful if you have custom validation needs. **Note:** The error message props do not work with useForm and is only applicable within our form input components when useState is being utilized. See the [useForm Docs](/web/hooks/use-form#set-error) for example use cases with useForm. ```jsx live () => { const [values, setValues] = useState(null); return ( ); }; ``` ## Descriptors display Use the `descriptorsDisplay` prop to set the orientation of the error message and subtext descriptor content. Available variants include 'column' and 'row'. The default is set to 'row'. Use the [FormProvider](/web/ui/form-provider#descriptors-display) and `descriptorsDisplay` to set the descriptors orientation across an entire form. ```jsx live () => { const [values, setValues] = useState(null); return ( ); }; ``` ## Label Use the `startDateLabel` and `endDateLabel` props to display a label above the input. To hide the input label set `hideLabel` to `true`. ```jsx live () => { const form = useForm(); return ( ); }; ``` ### Hide label To hide the input label set `hideLabel` to `true`. ```jsx live () => { const form = useForm(); return ( ); }; ``` ### Legend Use `legend` to set a label above both inputs. ```jsx live () => { const form = useForm(); return ( ); }; ``` ## Helper Use the `startDateHelper` and `endDateHelper` props to display a help icon next to the start date and end date labels, respectively. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip) or a [Popover](/web/ui/popover). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live () => { const form = useForm(); return ( } model="helper-custom" validators={{ required: true }} /> ); }; ``` ## Disabled Set the `isDisabled` prop to `true` to disable the input fields so users cannot enter a value. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( ); }; ``` ## Validation Use the `validators` prop to set rules for the field to be valid. ```jsx live () => { const form = useForm({ defaultValues: { validate: { from: '07/07/2022', to: '07/01/2022' }, }, }); const { errors, isSubmitted, isSubmitSuccessful } = form.formState; const getIconProps = useCallback( (model) => { if (!isSubmitted) return null; let iconProps = {}; if (!!errors[model]) { iconProps = { icon: 'error', color: '$error1', size: '18px' }; } if (isSubmitSuccessful) { iconProps = { icon: 'check', color: '$success1', size: '18px' }; } const node = ; return { inputRightElement: { start: node, end: node } }; }, [isSubmitted, isSubmitSuccessful] ); return ( { return ( dayjs(v.to, 'DD/MM/YYYY').isAfter( dayjs(v.from, 'DD/MM/YYYY') ) || 'End date should be after start date' ); }, }, }} /> ); }; ``` ## Highlighted Use the `highlighted` prop to enable the background color for the input. You can use `FormProvider` and `highlighted` to enable the color to appear if validation is required. ```jsx live () => { const [values, setValues] = useState(null); return ( ); }; ``` ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( ); }; ``` ## Width Use the `width` prop to set the width of both input fields. ```jsx live () => { const form = useForm(); return ( ); }; ``` ## Enable outside scroll Set the `enableOutsideScroll` prop to `true` to enable scroll outside of the date input range component while the calendar is open. Default is set to `false`. ```jsx live () => { const [values, setValues] = useState({ from: '07/11/2022', to: '07/15/2022', }); return ( ); }; ``` ## Calendar clear button The `hasClearButton` prop adds a button to the calendar allowing the user to clear current entries. ```jsx live () => { const form = useForm(); return ( ); }; ``` ## Clearable Use the `isClearable` prop to include a clearable button for DateInputRange. By default, this is set to `false`. **Note:**
If you are using `useState`, you will need to pass the `onStartClear` and `onEndClear` props to handle clearing the data when the clear button is pressed. ```jsx live () => { const form = useForm({ defaultValues: { 'test-form-date': { from: '06/04/2022', to: '06/30/2022' }, }, }); const onSubmit = (data) => { console.log('data', data); }; return ( ); }; ``` ```jsx live () => { const [values, setValues] = useState({ from: '07/11/2022', to: '07/15/2022', }); return ( { setValues((prev) => ({ ...prev, from: null })); }} onEndClear={() => { setValues((prev) => ({ ...prev, to: null })); }} /> ); }; ``` ## Open position Use the `openPosition` prop to set where the calendars should open in relation to the date input fields. By default, it will open above or below the input based on the available space. To force a fixed position, set `openPosition` to `top` or `bottom`. It is recommended to use `enableOutsideScroll` as well so that users can adjust the position of the calendar on their screen after opening. **Note:** If the calendar is opened to a position where there is not enough screen space available to accommodate the calendar, it will shift the entire component into view. ```jsx live () => { const form = useForm(); return ( ); }; ``` ```jsx render ``` ```jsx render ``` The example below includes date input range field that open a date picker that implements the dialog design pattern. The dialog contains a calendar that uses the grid pattern to present buttons that enable the user to choose a day from the calendar. Choosing a date from the calendar closes the dialog and populates the date input field. When the dialog is opened, if the input field is empty, or does not contain a valid date, then the current date is focused in the calendar. Otherwise, the focus is placed on the day in the calendar that matches the value of the date input field. Opening the calendar from either the start date or end date button prompts the user to select the first day and then the last day. Adheres to the Date Picker Dialog WAI-ARIA design pattern. ```jsx live () => { const form = useForm({ defaultValues: { validate: { from: '07/01/2024', to: '07/08/2024' }, }, }); const { errors, isSubmitted, isSubmitSuccessful } = form.formState; const getIconProps = useCallback( (model) => { if (!isSubmitted) return null; let iconProps = {}; if (isSubmitSuccessful) { iconProps = { icon: 'check', color: '$success1', size: '18px', isScreenReadable: '{true}', title: 'Valid', }; } if (errors[model]) { iconProps = { icon: 'error', color: '$error1', size: '18px' }; } const node = ; return { inputRightElement: { start: node, end: node } }; }, [isSubmitted, isSubmitSuccessful] ); return ( { return date.getDay() === 0 || date.getDay() === 6; }} startingYear={2023} startDateLabel="From" endDateLabel="Until" startDateHelper="From date must be weekday" hasClearButton endDateHelper={ } startDatePlaceholder="" endDatePlaceholder="" subtext="Date format: mm/dd/yyyy" {...getIconProps('validate')} validators={{ required: true, validate: { isAfter: (v) => { return ( dayjs(v.to, 'DD/MM/YYYY').isAfter( dayjs(v.from, 'DD/MM/YYYY') ) || 'Until date should be after From date' ); }, }, }} /> ); }; ``` ```jsx render

``` ```jsx render ``` ```jsx render ``` ```jsx render ``` --- id: default-props-provider-v2 category: Providers title: V2DefaultPropsProvider description: Used to provide default props to all V2 child components. sourceIsTS: true subDirectory: DefaultPropsProvider --- ```jsx import { V2DefaultPropsProvider } from '@uhg-abyss/web/ui/DefaultPropsProvider'; ``` ## Usage `V2DefaultPropsProvider` is a powerful context provider that enables teams to establish consistent default props for any V2 component throughout their application. Instead of repeatedly specifying the same props across multiple instances of a component, you can define these defaults once at a higher level in your component tree. This approach offers several benefits: - **Consistency**: Enforce uniform styling and behavior across your application - **Maintainability**: Update default props in one place rather than hunting for each component instance - **Customization**: Create themed sections of your application by nesting providers with different defaults - **Flexibility**: Override defaults when needed or opt out entirely with [`disableDefaultProviderProps`](#opting-out-of-defaults) ```jsx {/* ...children */} ``` **Note:** This provider only applies to components from the V2 suite. It will not affect V1 or other non-V2 components. ## Opting out of defaults To opt out of the defaults provided by `V2DefaultPropsProvider`, you can set the `disableDefaultProviderProps` prop to `true` on the component. This will prevent the component from inheriting any default props set by the provider. ## Examples Here are some example use cases with different component configurations and default prop setups. ### V2Button ```jsx live-expanded Provider defaults Provider defaults with color override Opt out of provider defaults ``` ### V2Link ```jsx live-expanded Provider defaults Provider defaults with variant override Opt out of provider defaults ``` ### V2Accordion & V2Accordion.Header ```jsx live-expanded Provider defaults Provider defaults with icon override Opt out of provider defaults ``` ### V2Tabs & V2Tabs.Tab ```jsx live-expanded Provider defaults Provider defaults with subLabel override Opt out of provider defaults ``` --- id: divider category: Layout title: Divider description: Used to add visual or semantic separation between content. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=19923-77152 --- ```jsx import { Divider } from '@uhg-abyss/web/ui/Divider'; ``` ```jsx sandbox { component: 'Divider', inputs: [ { prop: 'orientation', type: 'select', options: [ { label: 'horizontal', value: 'horizontal' }, { label: 'vertical', value: 'vertical' }, ], }, { prop: 'margin', type: 'string', }, { prop: 'height', type: 'string', }, { prop: 'width', type: 'string', }, { prop: 'color', type: 'string', }, ] }

``` ## Usage ```jsx live () => { const VerticalDivider = () => ( ); return (

Abyss Divider component

Add visual separation between content Orientation Width Height Color ); }; ``` ## Orientation Use the `orientation` prop to adjust the orientation to either `horizontal` or `vertical`. The default setting is `horizontal`. ```jsx live ``` ```jsx live

``` ## Width and height Use the `width` and `height` props to set the desired sizing dimensions. When `horizontal` orientation is selected the settings are applied as follows: - `width` : determines the left-to-right length of the of the divider; default setting is `100%` - `height` : determines the thickness of the divider; default setting is `2px` ```jsx live ``` When `vertical` orientation is selected the settings are applied as follows: - `width` : determines the thickness of the divider; default setting is `2px` - `height` : determines the top-to-bottom length of the of the divider; default setting is `100%` ```jsx live

``` ## Color Use the `color` property to set the color of the divider. The default setting is `$gray4`. ```jsx live ``` ```jsx render ``` ```jsx render ``` --- id: donut category: Data Visualization title: Donut slug: /web/ui/charts/donut description: A graphical representation of data in a circular-shaped graph with a cutout. design: https://www.figma.com/design/NnKHAtlU3Q0Xq3RzN9PJe1/Abyss-Data-Visualization?node-id=3-22730 --- **Note**: JPG and PNG download options are not compatible with Safari. As an alternative, please use the PDF option or take a screenshot. ```jsx import { Charts } from '@uhg-abyss/web/ui/Charts'; ``` ## Donut chart Simple Donut chart with two data sets having `title` and `subtitle` props passed. `xAxisLabel` and `yAxisLabel` are required props for chart. ```jsx live () => { const labels = ['Promoters', 'Passives', 'Detractors']; const data = { labels, datasets: [ { label: 'Score', data: [65, 59, 80], backgroundColor: [ '$primaryDvz1', Charts.pattern.draw('line', '$secondaryDvz1'), Charts.pattern.draw('diagonal', '$purpleDvz1'), ], borderColor: ['$primaryDvz1', '$secondaryDvz1', '$purpleDvz1'], }, ], }; return (

); }; ``` ## Donut options Pass `cutout`, `rotation`, `circumference` values to options of the Donut chart to set the thickness of the arc, the start angle to draw the arc from, and the sweep to allow the arcs to cover. The default values are `50%`, `0`, `360`, respectively. ```jsx live () => { const labels = ['Promoters', 'Passives', 'Detractors']; const data = { labels, datasets: [ { label: 'Donut Options', data: [65, 65, 65], backgroundColor: [ '$primaryDvz1', Charts.pattern.draw('line', '$secondaryDvz1'), Charts.pattern.draw('diagonal', '$purpleDvz1'), ], borderColor: ['$primaryDvz1', '$secondaryDvz1', '$purpleDvz1'], }, ], }; return (

); }; ``` ## Limitation Limiting the number of data points to 6. If the data set is larger than 6 items or the donut segments are small in size , we recommend using a different chart type for better readability, such as Bar Chart. ```jsx live () => { const labels = [ 'Promoters', 'Passives', 'Detractors', 'Buyers', 'Recruiters', 'Sellers', ]; const data = { labels, datasets: [ { label: 'Dataset', data: [65, 59, 80, 81, 56, 55], backgroundColor: [ '$primaryDvz1', Charts.pattern.draw('line', '$secondaryDvz1'), Charts.pattern.draw('diagonal', '$purpleDvz1'), Charts.pattern.draw('dot', '$tangerineDvz1'), Charts.pattern.draw('dash', '$sapphireDvz1'), Charts.pattern.draw('weave', '$gray6'), ], borderColor: [ '$primaryDvz1', '$secondaryDvz1', '$purpleDvz1', '$tangerineDvz1', '$sapphireDvz1', '$gray6', ], }, ], }; return (

); }; ``` ## Data structure Data in the datasets can be different structures and can be found in the Data Structures docs. When using the Donut chart type, the parsing object should have a `key` item that points to the value to look at. In this example, the Donut chart will show two items with values 1500 and 500. ```jsx live () => { const labels = ['Sales', 'Purchases']; const data = { labels, datasets: [ { label: 'Dataset 1', data: [ { id: 'Sales', nested: { value: 1500 } }, { id: 'Purchases', nested: { value: 500 } }, ], backgroundColor: ['$primaryDvz1', '$secondaryDvz1'], borderColor: ['$primaryDvz1', '$secondaryDvz1'], }, ], }; return (

); }; ``` ## Options Use `options` prop to customize the chart level and dataset level. Configuration for the options can be found in the Options docs. ```jsx live () => { const labels = ['Promoters', 'Passives', 'Detractors']; const data = { labels, datasets: [ { label: 'Dataset 1', data: [65, 59, 80], backgroundColor: [ '$tangerineDvz1', Charts.pattern.draw('dot', '$sapphireDvz1'), Charts.pattern.draw('dash', '$statusDvz1'), ], borderColor: ['$tangerineDvz1', '$sapphireDvz1', '$statusDvz1'], datalabels: { labels: { index: { formatter: function (value, ctx) { const total = ctx.dataset.data.reduce( (previousValue, currentValue) => { return previousValue + currentValue; } ); const percentage = Math.floor((value / total) * 100 + 0.5); return [ctx.chart.data.labels[ctx.dataIndex], `${percentage}%`]; }, }, }, }, }, ], }; return (

{ return previousValue + currentValue; } ); const percentage = Math.floor( (pointValue / total) * 100 + 0.5 ); return `${dataset.label}: ${percentage}%`; }, }, }, }, }} />

); }; ``` ## Chart description Use `chartDescription` prop to describe the chart, which will be shown in the chart description accordion below the view data table accordion. The default value of `chartDescription` is `null`. Whether displayed or not, the chart description accordion, including its content, are announced as the “long description” for the chart. ```jsx live () => { const labels = ['Promoters', 'Passives', 'Detractors', 'Buyers']; const data = { labels, datasets: [ { label: 'NPS Visitors', data: [22, 65, 75, 85], backgroundColor: [ '$tangerineDvz1', Charts.pattern.draw('dash', '$sapphireDvz1'), Charts.pattern.draw('weave', '$redDvz1'), Charts.pattern.draw('line', '$statusDvz1'), ], borderColor: [ '$tangerineDvz1', '$sapphireDvz1', '$redDvz1', '$statusDvz1', ], }, ], }; return (

); }; ``` ## Chart type Use `chartType` prop to describe the type of Donut chart. The default value is `Donut Chart`. ```jsx live () => { const labels = ['Promoters', 'Passives']; const data = { labels, datasets: [ { label: 'Dataset 1', data: [65, 50], backgroundColor: [ '$primaryDvz1', Charts.pattern.draw('dot', '$secondaryDvz1'), ], borderColor: ['$primaryDvz1', '$secondaryDvz1'], }, ], }; return (

); }; ``` ## Pattern donut chart Use `Charts.pattern` prop in dataset to make patterns in the Donut chart, which helps viewers with vision deficiencies. Refer to the Patternomaly library to generate patterns to fill datasets. ```jsx live () => { const labels = ['Promoters', 'Passives', 'Detractors', 'Buyers']; const data = { labels, datasets: [ { data: [45, 25, 20, 10], backgroundColor: [ Charts.pattern.draw('square', '$primaryDvz1'), Charts.pattern.draw('circle', '$secondaryDvz1'), Charts.pattern.draw('diamond', '$purpleDvz1'), Charts.pattern.draw('triangle', '$tangerineDvz1'), ], borderColor: [ Charts.pattern.draw('square', '$primaryDvz1'), Charts.pattern.draw('circle', '$secondaryDvz1'), Charts.pattern.draw('diamond', '$purpleDvz1'), Charts.pattern.draw('triangle', '$tangerineDvz1'), ], }, ], }; return ( ); }; ``` ## Title offset Use `titleOffset` prop to change the heading level of graph title in a page. The default value is `1`. You can use titleOffset={1|2|3|4|5}. ```jsx live () => { const labels = ['Promoters', 'Passives', 'Detractors']; const data = { labels, datasets: [ { label: 'Dataset', data: [65, 59, 80], backgroundColor: [ '$primaryDvz1', Charts.pattern.draw('line', '$secondaryDvz1'), Charts.pattern.draw('diagonal', '$purpleDvz1'), ], borderColor: ['$primaryDvz1', '$secondaryDvz1', '$purpleDvz1'], }, ], }; return (

); }; ``` ## Data labels Use `datalabels` plugins option to add custom labels to the Donut chart.`datalabels` can also be configured in dataset level, as shown below. More details for customizing datalabels can found here Datalabels ```jsx live () => { const labels = ['Promoters', 'Passives', 'Detractors']; const data = { labels, datasets: [ { label: 'Dataset', data: [65, 59, 80], backgroundColor: [ '$primaryDvz1', Charts.pattern.draw('line', '$secondaryDvz1'), Charts.pattern.draw('diagonal', '$purpleDvz1'), ], borderColor: ['$primaryDvz1', '$secondaryDvz1', '$purpleDvz1'], datalabels: { labels: { index: { formatter: function (value, ctx) { const total = ctx.dataset.data.reduce( (previousValue, currentValue) => { return previousValue + currentValue; } ); const percentage = Math.floor((value / total) * 100 + 0.5); return [ctx.chart.data.labels[ctx.dataIndex], `${percentage}%`]; }, }, }, }, }, ], }; return (

{ return previousValue + currentValue; } ); const percentage = Math.floor( (pointValue / total) * 100 + 0.5 ); return `${dataset.label}: ${percentage}%`; }, }, }, }, }} />

); }; ``` ## Hiding dropdowns Use the `hideDataTable` prop to remove the "View Data Table" accordion dropdown below the chart. Use the `hideDownloadDropdown` prop to remove the download options dropdown in the upper right corner of the chart. The default setting for both options is `false`. ```jsx live () => { const labels = ['Promoters', 'Passives', 'Detractors']; const data = { labels, datasets: [ { label: 'Score', data: [65, 59, 80], backgroundColor: [ '$primaryDvz1', Charts.pattern.draw('line', '$secondaryDvz1'), Charts.pattern.draw('diagonal', '$purpleDvz1'), ], borderColor: ['$primaryDvz1', '$secondaryDvz1', '$purpleDvz1'], }, ], }; return (

); }; ``` ## Showing dropdowns Use the `openDataTable` prop to expand the "View Data Table" accordion dropdown below the chart by default. The default is `false`. Setting to `true` expands the accordion by default, while setting it to `'always'` prevents the accordion from being collapsible, and is thus always open. ```jsx live () => { const labels = ['Promoters', 'Passives', 'Detractors']; const data = { labels, datasets: [ { label: 'Score', data: [65, 59, 80], backgroundColor: [ '$primaryDvz1', Charts.pattern.draw('line', '$secondaryDvz1'), Charts.pattern.draw('diagonal', '$purpleDvz1'), ], borderColor: ['$primaryDvz1', '$secondaryDvz1', '$purpleDvz1'], }, ], }; return (

); }; ``` **Note: Use `doughnut` for chart config overrides of chart.js defaults instead of `donut`** ```jsx render ``` ```jsx render ```

Chart accessibility requirements

- Text contrast must be 4.5:1 or greater - Single chart bar color contrast must be 3:1 or greater - Donut segments must be more than a difference in color - For donut charts: use patterns

Chart “long description”

- Whether displayed or not, the chart description accordion, including its content, are announced as the “long description” for the chart. ```jsx live () => { const labels = ['Promoters', 'Passives', 'Detractors']; const data = { labels, datasets: [ { label: 'Score', data: [65, 59, 80], backgroundColor: [ '$primaryDvz1', Charts.pattern.draw('line', '$secondaryDvz1'), Charts.pattern.draw('diagonal', '$purpleDvz1'), ], borderColor: ['$primaryDvz1', '$secondaryDvz1', '$purpleDvz1'], }, ], }; return (

); }; ```

Reduced Motion

Animations and transitions that have been changed when a user has `prefers-reduced-motion` set to `reduced` for all Data Visualizations: - No inflation of bars, sections or lines upon initial data rendering - Data point tooltip navigation has animation removed - View Data Table Accordion has transitions removed ```jsx render ```

Known screen reader issues

NVDA and JAWS

Datapoint navigation announce tooltip content twice - The second time includes chart name --- id: drag-and-drop category: Content title: DragAndDrop description: Used to create a dynamic set of data that can easily be moved by the user. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=6830-24990 --- ```jsx import { DragAndDrop } from '@uhg-abyss/web/ui/DragAndDrop'; ``` ```jsx render ``` ## Drag and drop - The `id` prop must be unique for each item. - The `columnContent` prop sets the content for a column - The `columnItems` prop set the array of items for a column. - The `isVisible` prop set the default icon's visibility. - Note: Please cache content preferences at the API level. ```jsx live () => { state = [ { id: 'col1', columnContent: 'Section 1', isVisible: true, columnItems: [ { id: 'task1', content: 'content 1', isVisible: true, }, { id: 'task2', content: 'content 2', isVisible: true }, { id: 'task3', content: 'content 3', isVisible: true }, { id: 'task4', content: 'content 4', isVisible: true }, ], }, { id: 'col2', columnContent: 'Section 2', isVisible: true, columnItems: [ { id: 'task5', content: 'content 5', isVisible: true }, { id: 'task6', content: 'content 6', isVisible: true }, { id: 'task7', content: 'content 7', isVisible: true }, { id: 'task8', content: 'content 8', isVisible: true, }, ], }, { id: 'col3', columnContent: 'Section 3', isVisible: true, columnItems: [ { id: 'task9', content: 'content 9', isVisible: true }, { id: 'task10', content: 'content 10', isVisible: true }, ], }, ]; const [data, setData] = useState(state); return ( ); }; ``` ## Actions Actions can be passed in the column or row levels of drag and drop using the `action` prop. Within the `action` prop an icon can be set using the `icon` prop and a method for the icon can be set using the `method` prop. ```jsx live () => { state = [ { id: 'col1', columnContent: 'Section 1', isVisible: true, action: { icon: ( ), method: (column) => { console.log('column clicked: ', column); }, }, columnItems: [ { id: 'task1', content: 'content 1', isVisible: true, action: { icon: ( ), method: (row, column) => { console.log('row clicked: ', row, column); }, }, }, { id: 'task2', content: 'content 2', isVisible: true, action: { icon: ( ), method: (row, column) => { console.log('row clicked: ', row, column); }, }, }, { id: 'task3', content: 'content 3', isVisible: true, action: { icon: ( ), method: () => { console.log('Action clicked'); }, }, }, { id: 'task4', content: 'content 4', isVisible: true, action: { icon: ( ), method: () => { console.log('Action clicked'); }, }, }, ], }, ]; const [data, setData] = useState(state); return ; }; ``` ## Hiding actions Actions can be disabled by setting the `hideAction` prop to `false`. The default is set to `true`. ```jsx live () => { state = [ { id: 'col1', columnContent: 'Section 1', isVisible: true, hideAction: true, columnItems: [ { id: 'task1', content: 'content 1', isVisible: true, hideAction: true, }, { id: 'task2', content: 'content 2', isVisible: true, hideAction: true, }, { id: 'task3', content: 'content 3', isVisible: true, hideAction: true, }, { id: 'task4', content: 'content 4', isVisible: true, hideAction: true, }, ], }, ]; const [data, setData] = useState(state); return ; }; ``` ## Dynamic content `columnContent` and row `content` can take in either a node or function. When passing a function to row `content` you have access to column, row, and setData. When passing a function to `columnContent` you have access to column and setData. The setData method is the set function returned from the `useState` hook. ```jsx live () => { const updateRow = (rowData, columnData, setData) => { setData((prevData) => prevData.map((col) => col.id === columnData.id ? { ...col, columnItems: col.columnItems.map((rowItem) => rowData.id === rowItem.id ? { ...rowItem, checked: !rowData.checked } : rowItem ), } : col ) ); }; const updateColumn = (columnData, setData) => { setData((prevData) => prevData.map((col) => col.id === columnData.id ? { ...col, checked: !columnData.checked, } : col ) ); }; const state = [ { id: 'col1', checked: false, hideAction: true, columnContent: (columnData, setData) => { return (

updateColumn(columnData, setData)} />

); }, columnItems: [ { id: 'task1', hideAction: true, content: (rowData, columnData, setData) => { return (

updateRow(rowData, columnData, setData)} />

); }, }, { id: 'task2', content: (rowData, columnData, setData) => { return (

updateRow(rowData, columnData, setData)} />

); }, hideAction: true, }, ], }, ]; const [data, setData] = useState(state); return ; }; ``` ## Disabling drag Columns and rows can be locked and disabled causing them to not be draggable by using the `isDragDisabled` prop. Note: Please keep locked items at the top or bottom. ```jsx live () => { state = [ { id: 'col1', columnContent: 'Section 1', isVisible: true, columnItems: [ { id: 'task1', content: 'content 1', isVisible: true, }, { id: 'task2', content: 'content 2', isVisible: true }, { id: 'task3', content: 'content 3', isVisible: true, props: { isDragDisabled: true }, }, { id: 'task4', content: 'content 4', isVisible: true, props: { isDragDisabled: true }, }, ], }, { id: 'col2', columnContent: 'Section 2', isVisible: true, columnItems: [ { id: 'task5', content: 'content 5', isVisible: true, }, { id: 'task6', content: 'content 6', isVisible: true }, { id: 'task7', content: 'content 7', isVisible: true, props: { isDragDisabled: true }, }, { id: 'task8', content: 'content 8', isVisible: true, props: { isDragDisabled: true }, }, ], }, { id: 'col3', isDragDisabled: true, // Disables the entire column from being dragged columnContent: 'Section 3', isVisible: true, columnItems: [ { id: 'task9', content: 'content 9', isVisible: true, }, { id: 'task10', content: 'content 10', isVisible: true }, { id: 'task11', content: 'content 11', isVisible: true, props: { isDragDisabled: true }, }, { id: 'task12', content: 'content 12', isVisible: true, props: { isDragDisabled: true }, }, ], }, ]; const [data, setData] = useState(state); return ; }; ``` ## Disable accordion The accordion can be disabled using the `accordionDisabled` prop. ```jsx live () => { state = [ { id: 'col1', columnContent: 'Section 1', isVisible: true, columnItems: [ { id: 'task1', content: 'content 1', isVisible: true, }, { id: 'task2', content: 'content 2', isVisible: true }, { id: 'task3', content: 'content 3', isVisible: true }, { id: 'task4', content: 'content 4', isVisible: true }, ], }, { id: 'col2', columnContent: 'Section 2', isVisible: true, columnItems: [ { id: 'task5', content: 'content 5', isVisible: true }, { id: 'task6', content: 'content 6', isVisible: true }, { id: 'task7', content: 'content 7', isVisible: true }, { id: 'task8', content: 'content 8', isVisible: true, }, ], }, { id: 'col3', columnContent: 'Section 3', isVisible: true, columnItems: [ { id: 'task9', content: 'content 9', isVisible: true }, { id: 'task10', content: 'content 10', isVisible: true }, ], }, ]; const [data, setData] = useState(state); return ; }; ``` ## Callbacks ### onSave, onCancel, onCustomize - The `onSave` callback is fired when the drag and drop order is saved. - The `onCancel` callback is fired when the drag and drop order customization is canceled. - The `onCustomize` callback is fired when the "Customize Order" button is clicked. `onSave` and `onCancel` can take two positional arguments. The first argument is the state of the data when the "Customize Order" button is clicked. The second argument is the state of the data when the save or cancel button is clicked. `onCustomize` accepts one argument: the state of the data when the button was clicked. ```jsx live () => { const state = [ { id: 'col1', columnContent: 'Section 1', isVisible: true, columnItems: [ { id: 'task1', content: 'content 1', isVisible: true, }, { id: 'task2', content: 'content 2', isVisible: true }, { id: 'task3', content: 'content 3', isVisible: true }, { id: 'task4', content: 'content 4', isVisible: true }, ], }, ]; const [data, setData] = useState(state); const onSave = (oldData, data) => { console.log('onSave data:', data); console.log('onSave oldData:', oldData); }; const onCancel = (oldData, data) => { console.log('onCancel data', data); console.log('onCancel oldData:', oldData); }; const onCustomize = (data) => { console.log('onCustomize data:', data); }; return ( ); }; ``` ### onDragEnd Callback fired once a drag has ended. It is the responsibility of this responder to synchronously apply changes that has resulted from the drag. ```jsx live () => { state = [ { id: 'col1', columnContent: 'Section 1', isVisible: true, columnItems: [ { id: 'task1', content: 'content 1', isVisible: true, }, { id: 'task2', content: 'content 2', isVisible: true }, { id: 'task3', content: 'content 3', isVisible: true }, { id: 'task4', content: 'content 4', isVisible: true }, ], }, ]; const [data, setData] = useState(state); onDragEnd = (result) => { const { destination, source, draggableId } = result; const findColumnIndex = (element) => { return element.id === result.source.droppableId; }; if (!destination) { return; } if ( destination.droppableId === source.droppableId && destination.index === source.index ) { return; } if (destination.droppableId !== source.droppableId) { return; } if (result.type === 'column') { const columns = Array.from(data); const [reorderedItem] = columns.splice(result.source.index, 1); columns.splice(result.destination.index, 0, reorderedItem); setData(columns); } else if (result.type === 'row') { if (destination.droppableId === 'column') { return; } const columns = Array.from(data); const columnIndex = columns.findIndex(findColumnIndex); const { columnItems } = columns[columnIndex]; const [reorderedItem] = columnItems.splice(result.source.index, 1); columnItems.splice(result.destination.index, 0, reorderedItem); setData(columns); } }; return ; }; ``` ## Responders Responders are top level application events that you can use to perform your own state updates, style updates, as well as to make screen reader announcements. More information about onBeforeCapture, onBeforeDragStart, onDragStart, onDragUpdate, and onDragEnd can be found on the beautiful Dnd docs. ```jsx render ``` ```jsx render ```

No WAI-ARIA 1.1 standard

There is no WAI-ARIA 1.1 design pattern to follow for implementing DragAndDrop. Given the complexity of drag and drop coupled with the added visibility functionality, the implementation attempts to provide a fully accessible solution.

Keyboard and touch screen support

DragAndDrop should be fully functional using a keyboard and touchscreen. This includes meeting WCAG 2.2 SC2.5.7: Dragging Movements (Level AA) supplying up/down buttons to a support single pointer alternative to dragging. Keyboard support works with both up/down buttons and drag controller (select then use up/down arrow keys). The downside of this is that it adds an additional 2 tab stops per row. Removing the up/down arrow from keyboard operations may be considered in the future.

Screen reader support (implementation)

Screen reader support attempts to meaningful description of the contents, features and status updates for collapsing sections and the repositioning and visibility functionality of all entries. Given the complexity of these and the underlying ARIA, significant variations in BrAT have been noted.

Screen reader feature support

- **NVDA** - **Visibility:** Good - **Custom Order:** Very good - **JAWS** - **Visibility:** Good, but verbose instructions - **Custom Order:** Very good, but verbose instructions - **VoiceOver** - **Visibility:** Fair to Good, not as complete - **Custom Order:** Fair to Good, not as complete ```jsx live () => { state = [ { id: 'artist1', columnContent: 'The Beatles', isVisible: true, columnItems: [ { id: 'album1', content: 'Abbey Road', isVisible: true }, { id: 'album2', content: 'The Beatles - White Album', isVisible: true }, { id: 'album3', content: 'Let It Be', isVisible: true }, { id: 'album4', content: 'Sgt. Peppers Lonely Hearts Club Band', isVisible: true, }, ], }, { id: 'artist2', columnContent: 'Muse', isVisible: true, columnItems: [ { id: 'album5', content: 'The 2nd Law', isVisible: true }, { id: 'album6', content: 'Drones', isVisible: true }, { id: 'album7', content: 'The Resistance', isVisible: true }, { id: 'album8', content: 'Simulation Theory', isVisible: true }, ], }, { id: 'artist3', columnContent: 'The Rolling Stones', isVisible: true, columnItems: [ { id: 'album9', content: 'Exile on Main Street', isVisible: true }, { id: 'album10', content: 'Some Girls', isVisible: true }, ], }, ]; const [data, setData] = useState(state); return ( ); }; ```

Reduced Motion

Animations and transitions that have been changed when a user has `prefers-reduced-motion` set to `reduced`: - Section control "accordion" has transitions removed - When using buttons to reorder elements, drag transition is removed ```jsx render ``` ```jsx render ``` --- id: drawable-canvas category: Forms title: DrawableCanvas description: Used to capture signatures. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=43685-121609 --- ```jsx import { DrawableCanvas } from '@uhg-abyss/web/ui/DrawableCanvas'; ``` ```jsx render ``` ## Usage ```jsx sandbox { component: 'DrawableCanvas', inputs: [ { prop: 'backgroundColor', type: 'string', }, { prop: 'penColor', type: 'string', }, { prop: 'minPenWidth', type: 'number', }, { prop: 'maxPenWidth', type: 'number', }, { prop: 'hideSignLine', type: 'boolean', }, { prop: 'hideSave', type: 'boolean', }, ], } () => { return ( console.log(data)} /> ); } ``` ## Canvas a11y This component is NOT ACCESSIBLE for keyboard users and is limited to mouse interactions. For a canvas drawing tool to be accessible there are two aspects that need to be considered: - Keyboard support to allow some form of rudimentary drawing capability, which is likely to be very difficult. - Screen reader support to ensure the canvas can be navigated and exited intelligently. ### Keyboard support Paint programs and canvases inherently assume the use of a mouse, touchscreen, or stylus. There is no WAI-ARIA or other standard interface for keyboard support. ### Screen reader support Very few drawing applications for screen readers use the canvas method; instead, they opt for different techniques. They are more of a "drawing" (object entry) program where users define elements to put on the screen. See, for example, SVG Draw. Even if the canvas does not work with a keyboard, screen reader users will likely encounter pages with them. These should provide some minimal information about what is displayed so they understand what is there. This must include some indication there is a canvas that users can draw on using a mouse, finger, or stylus. If canvas entry is required (like preparing a signature), there must be some indication somewhere on the page of how keyboard users (including those running screen readers) can enter equivalent content. Instructions for any signature element must provide some alternative, accessible approach that supplies an equivalent such as: - Keyboard entry of a signature alternative - Upload a signature graphic A detailed explanation of these approaches can be found on the [Accessibility Tab](/web/ui/drawable-canvas?tab=accessibility). ## Background color Use the `backgroundColor` prop to change the background color of the canvas. The default value is `$white`. ```jsx live () => { return ( { console.log('save btn click', data); }} /> ); }; ``` ## Pen color Use the `penColor` prop to change the color of the pen. The default value is `$black`. ```jsx live () => { return ( { console.log('save btn click', data); }} /> ); }; ``` ## Min and max width Use the `minPenWidth` and `maxPenWidth` props to change the width of the pen. The default values of `minPenWidth` and `maxPenWidth` are `0.5` and `2.5`. ```jsx live () => { return ( { console.log('save btn click', data); }} /> ); }; ``` ## Hide sign line Use the `hideSignLine` prop to hide the sign line of the canvas. The default value is `false`. ```jsx live () => { return ( { console.log('save btn click', data); }} /> ); }; ``` ## Canvas methods The `canvas` object can be imported from the `@uhg-abyss/web/ui/DrawableCanvas` package: ```jsx import { canvas } from '@uhg-abyss/web/ui/DrawableCanvas'; ``` It provides the following methods: - `saveAsPng`: Creates a data URL of the canvas data in PNG format - `saveAsJpg`: Creates a data URL of the canvas data in JPG format - `saveAsSvg`: Creates a data URL of the canvas data in SVG format - `saveAsSvgWithBackGround`: Creates a data URL of the canvas data in SVG format with a background color - `dataURLToBlob`: Converts a data URL to a blob - `download`: Downloads the given canvas data with the specified file name Below is an example of how to save the canvas data as a JPG file: ```jsx live () => { return ( { const JpgData = canvas.saveAsJpg(data); console.log('JpgData', JpgData); canvas.download(JpgData, 'canvas.jpg'); }} /> ); }; ``` ## Hide save button Use the `hideSave` prop to hide the save button of the canvas. The default value is `false`. ```jsx live () => { return ; }; ``` ## Custom ref Using the `ref` prop allows components outside the `DrawableCanvas` to access the canvas's data. ```jsx live () => { const canvasRef = useRef(null); return ( ); }; ``` ```jsx render ``` ```jsx render ```

e-Signatures

The accessibility of e-Signatures has a lot of considerations. If a team chooses to use an interactive canvas—such as `DrawableCanvas`—they are responsible for providing a keyboard-accessible alternative based on their application and business requirements. DocuSign is a leader in e-Signatures and has been audited for accessibility. Their video, DocuSign eSignature (and Beyond), shows their approach for supporting screen reader users. As those who have tried it may know, signing with anything other than a pen or stylus is not easy to do. Finger signing on a screen is often crude and imprecise at best. Signing with a mouse or trackball can be even harder. Supporting one or both of the follwing more accessible approaches gives any user who is not satisfied with the canvas another option.

Keyboard Entry of Signature Facsimiles

The best approach, as shown in the video, is simple: Use text boxes to enter name and initials (if necessary). The entered text is used to create a graphic equivalent typically using a cursive font. The resulting text is converted to an image and copied in the same way the canvas content is.

Upload Image

Another common approach is to allow the user to upload their own signature as an image. This allows them to sign on paper and scan it to create the signature and not rely on a user interface component. DocuSign and others support this approach. However, this approach requires users to create their own signature graphic, which shifts the signature generation from Abyss to the user. Though many users may have a signature image already available, delegating this task to them with no alternative is not acceptable.

Legal Review

Any e-Signature implementation, given that it almost certainly applies to some contractual agreement, will need some review by the legal department to ensure it is valid in all forms. --- id: drawer-v2 category: Overlay title: V2Drawer description: Displays an overlay area at any side of the screen. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=10763-41143 subDirectory: Drawer/v2 sourceIsTS: true --- ```jsx render ``` ```jsx import { V2Drawer } from '@uhg-abyss/web/ui/Drawer'; ``` ```jsx sandbox { component: 'V2Drawer', inputs: [ { prop: 'children', type: 'string', }, { prop: 'size', type: 'select', options: [ { label: '$sm', value: '$sm' }, { label: 'custom', value: '600' }, ], }, { prop: 'position', type: 'select', options: [ { label: 'left', value: 'left' }, { label: 'right', value: 'right' }, ], }, { prop: 'closeOnClickOutside', type: 'boolean', }, ], } () => { const [isOpen, setIsOpen] = useState(false); return ( setIsOpen(false)} > Press escape to close the drawer setIsOpen(true)} aria-haspopup="dialog"> Toggle Drawer ); } ``` ## Opening the drawer There are two methods of controlling the open state of a V2Drawer: by using the `useOverlay` hook or by using the `isOpen` prop. ### useOverlay The [useOverlay hook](/web/hooks/use-overlay) returns an object containing various methods used to control the state of the modal. Each modal must be assigned a unique `model` prop and wrapped in an [OverlayProvider](/web/ui/overlay-provider). **Note:** If you're encountering issues ensure the modal is properly wrapped in an `OverlayProvider` / refer to the docs perspective pages for troubleshooting. ```jsx live () => { const drawer = useOverlay('drawer-form'); const form = useFormV2(); const onSubmit = (data) => { console.log('data', data); }; const footer = ( { form.handleSubmit(onSubmit)(); if (!form.formState.isValid) { return { preventClose: true }; } }} > Submit Close ); return ( drawer.open()} aria-haspopup="dialog"> Toggle Drawer { console.log('Drawer closed'); }} footer={footer} > ); }; ``` ### useState Using the `useState` hook to set the open state of the drawer. ```jsx live () => { const [isOpen, setIsOpen] = useState(false); const form = useFormV2(); const onSubmit = (data) => { console.log('data', data); }; const footer = ( { form.handleSubmit(onSubmit)(); if (!form.formState.isValid) { return { preventClose: true }; } }} > Submit Close ); return ( setIsOpen(true)} aria-haspopup="dialog"> Toggle Drawer setIsOpen(false)} footer={footer} > ); }; ``` ## Header Use the `header` prop to set the header of the drawer. This prop is optional but strongly recommended. It accepts a React node, and is typically a string representing the title of the drawer. If not using `header`, please use `ariaLabel` to provide a title and keep the component accessible. ```jsx live () => { const [isHeaderDrawerOpen, setHeaderDrawerOpen] = useState(false); const [isNoHeaderDrawerOpen, setNoHeaderDrawerOpen] = useState(false); const [isCustomHeaderDrawerOpen, setCustomHeaderDrawerOpen] = useState(false); const sharedText = 'Lorem ipsum odor amet, consectetuer ultricey elit. Pretium rhoncus non ultricies arcu ultricies luctus montes. Consequat nostra risus proin netus condimentum cursus. Donec tempor orci aliquet, primis feugiat ad leo ullamcorper malesuada. Efficitur mollis non tristique himenaeos iaculis. Fusce viverra pellentesque sit iaculis porttitor vulputate. Aliquam pretium faucibus inceptos per porta habitasse. Ipsum praesent auctor fames taciti tortor. Venenatis aenean blandit tellus neque penatibus laoreet metus lorem eleifend. '; const customHeader = ( Custom Header ); return ( setHeaderDrawerOpen(false)} > {sharedText} setCustomHeaderDrawerOpen(false)} > {sharedText} setNoHeaderDrawerOpen(false)} > {sharedText} setHeaderDrawerOpen(true)} aria-haspopup="dialog" > Header setCustomHeaderDrawerOpen(true)} aria-haspopup="dialog" > Custom Header setNoHeaderDrawerOpen(true)} aria-haspopup="dialog" > No Header ); }; ``` ## Footer Use the `footer` prop to add a footer to the drawer. It accepts a React node, typically one or two buttons. **Note:** If closing the drawer with a button please refer to our [V2Drawer.Close](#v2drawerclose) documentation. ```jsx live () => { const [isOpen, setIsOpen] = useState(false); const footer = Close; return ( setIsOpen(false)} > Lorem ipsum odor amet, consectetuer adipiscing elit. Pretium rhoncus non ultricies arcu ultricies luctus montes. Consequat nostra risus proin netus condimentum cursus. Donec tempor orci aliquet, primis feugiat ad leo ullamcorper malesuada. Efficitur mollis non tristique himenaeos iaculis. Fusce viverra pellentesque sit iaculis porttitor vulputate. Aliquam pretium faucibus inceptos per porta habitasse. Ipsum praesent auctor fames taciti tortor. Venenatis aenean blandit tellus neque penatibus laoreet metus lorem eleifend. setIsOpen(true)} aria-haspopup="dialog"> Toggle Drawer ); }; ``` ## Closing the drawer `V2Drawer` shows a close (X) button in the top right corner by default (to hide it, set `hideClose={true}`). **Important:** For proper animation, always use the [``](#v2drawerclose) sub-component when adding a button for closing the drawer. Direct state manipulation (like `setIsOpen(false)`) will skip the closing animation. ### V2Drawer.Close The `` sub-component is used to close `V2Drawer` with animation, and accepts all the same props as the [V2Button](/web/ui/button-v2) component. The only difference is in how the `onClick` handler works: If your `onClick` returns `{ preventClose: true }`, the drawer will remain open. Otherwise, the drawer will close and play its animation. ```ts { { form.handleSubmit(onSubmit)(); // If the form is not valid, prevent the drawer from closing if (!form.formState.isValid) { return { preventClose: true }; } // Otherwise, the drawer will close }} > Submit / Close ; } ``` ```jsx live () => { const drawer = useOverlay('drawer-close'); const form = useFormV2(); const onSubmit = (data) => { console.log('data', data); }; return ( drawer.open()} aria-haspopup="dialog"> Toggle Drawer { form.handleSubmit(onSubmit)(); if (!form.formState.isValid) { return { preventClose: true }; } }} > Submit / Close } > ); }; ``` ### closeOnClickOutside Use the `closeOnClickOutside` prop to control whether a user can dismiss the drawer by clicking on the overlay. The default value is `true`. ```jsx live () => { const drawer = useOverlay('drawer-closeOnClickOutside'); return ( drawer.open()} aria-haspopup="dialog"> Toggle Drawer Not closing on outside click ); }; ``` ## Passing data External data can be passed into the drawer when using the `useOverlay` hook. The `open` and `toggle` methods returned by the hook accept an object of the following type: ```ts { isOpen?: boolean; data?: object; } ``` The `getState` method retrieves the state of the drawer as an object of the same type. ```jsx live () => { const StateOutput = styled('pre', { marginTop: '8px', }); const drawer = useOverlay('data-drawer'); const { isOpen, data } = drawer.getState(); return ( drawer.open({ firstName: 'John', lastName: 'Doe' })} aria-haspopup="dialog" > Open Drawer {JSON.stringify({ isOpen, data }, null, 2)}

First Name: {data && data.firstName}

Last Name: {data && data.lastName}

); }; ``` ## Size Use the `size` prop to set the width of the drawer. The options are `'$sm'` or custom. ```jsx live () => { const [isOpen, setIsOpen] = useState(false); const [size, setSize] = useState('450px'); const openDrawer = (size) => { setSize(size); setIsOpen(true); }; return ( openDrawer('$sm')} aria-haspopup="dialog"> Small (Default) openDrawer('600px')} aria-haspopup="dialog"> Custom setIsOpen(false)} size={size} /> ); }; ``` ## Position Use the `position` prop to set the position of the drawer. The default is `'right'`. ```jsx live () => { const [isOpen, setIsOpen] = useState(false); const [position, setPosition] = useState('left'); const openDrawer = (position) => { setPosition(position); setIsOpen(true); }; return ( setIsOpen(false)} position={position} /> openDrawer('left')} aria-haspopup="dialog"> Left openDrawer('right')} aria-haspopup="dialog"> Right ); }; ``` ## Overflow Overflow is handled within the content of the modal dialog. The header and footer, if present, will remain fixed. **Note:** If no header is provided and `hideClose={false}` the close button will be fixed to the top right corner of the drawer. ```jsx live () => { const drawer = useOverlay('overflow-drawer'); const footer = Close; return ( drawer.open()} aria-haspopup="dialog"> Toggle Drawer {Array.from(Array(50).keys()).map((item) => { return (

Overflow Example - Scroll

); })} ); }; ``` ```jsx render ``` ```jsx render ``` ```jsx render ```

Drawer Accessible Example

```jsx live () => { const drawer = useOverlay('drawer-footer'); const footer = Dismiss; return ( drawer.open()} aria-haspopup="dialog"> Open drawer {Array.from(Array(30).keys()).map((item) => { return (

Meaningless text to fill screen and force the creation of a scrolling region.

); })} ); }; ```

Drawer Content

The content included on the Drawer must be accessible. ```jsx live () => { const drawer = useOverlay('accessible-drawer'); return ( <> drawer.open()} aria-haspopup="dialog"> Toggle Drawer Button is accessible in drawer ); }; ```

Triggering Elements

Use the aria-haspopup attribute on buttons or other triggering elements that open content like dialogs, listboxes, trees, menus, grids, etc. Use a corresponding value that indicates what kind of popup will be displayed when the trigger element is activated. In turn, the element that pops up must be of the role indicated. For example use aria-haspop="dialog" on buttons that open modal dialogs. Be sure to include role="dialog" on the containing element of the dialog itself, too. See the docs on 'haspop' for more details:https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup aria-haspopup - Accessibility | MDN The aria-haspopup attribute indicates the availability and type of interactive popup element that can be triggered by the element on which the attribute is set.

Reduced Motion

Animations and transitions that have been changed when a user has `prefers-reduced-motion` set to `reduced`: - Transition upon expand/collapse is removed

Component Tokens

**Note:** Click on the token row to copy the token to your clipboard. ```jsx render ``` --- id: drawer category: Overlay title: Drawer description: Displays an overlay area at any side of the screen. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=22242-75820 subDirectory: Drawer/v1 --- ```jsx render ``` ```jsx import { Drawer } from '@uhg-abyss/web/ui/Drawer'; ``` ```jsx sandbox { component: 'Drawer', inputs: [ { prop: 'children', type: 'string', }, { prop: 'position', type: 'select', options: [ { label: 'left', value: 'left' }, { label: 'top', value: 'top' }, { label: 'bottom', value: 'bottom' }, { label: 'right', value: 'right' }, ], }, { prop: 'title', type: 'string', }, { prop: 'size', type: 'string', }, ], } () => { const [isOpen, setIsOpen] = useState(false); return ( setIsOpen(false)} > Press escape to close the drawer ); } ``` ## useOverlay Using the `useOverlay` hook lets the DOM handle form data and the overlay's state. To utilize the [useOverlay](/web/hooks/use-overlay) hook, the root or parent must be wrapped with the [OverlayProvider](/web/ui/overlay-provider). ```jsx live () => { const drawer = useOverlay('drawer-form'); const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return (

); }; ``` ## useState Using the `useState` hook to set the open state of the drawer. ```jsx live () => { const [isOpen, setIsOpen] = useState(false); const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( setIsOpen(false)} >

); }; ``` ## Title Use the `title` prop to set the title of the drawer. ```jsx live () => { const drawer = useOverlay('title-drawer'); return ( Custom Title ); }; ``` ## Passing data Use the `getState` method to retrieve the state of the drawer. Structure: `{ isOpen: Boolean, data: Object }`. Pass data into the open/toggle methods to use in the drawer. ```jsx live () => { const drawer = useOverlay('data-drawer'); const { data } = drawer.getState(); return (

First Name: {data && data.firstName}

Last Name: {data && data.lastName}

); }; ``` ## Size Use the `size` prop to set the width of the drawer. ```jsx live () => { const [isOpen, setIsOpen] = useState(false); const [size, setSize] = useState('450px'); const openDrawer = (size) => { setSize(size); setIsOpen(true); }; return ( setIsOpen(false)} size={size} > Press escape to close the drawer ); }; ``` ## Title align Use the `titleAlign` prop to align the position of the title. ```jsx live () => { const form = useForm(); const drawer = useOverlay('title-aligment'); const [align, setAlign] = useState('left'); const onSubmit = (data) => { console.log('data', data); }; return ( Title Alignment ); }; ``` ## Position Use the `position` prop to set the position of the drawer. ```jsx live () => { const [isOpen, setIsOpen] = useState(false); const [position, setPosition] = useState('left'); const openDrawer = (position) => { setPosition(position); setIsOpen(true); }; return ( setIsOpen(false)} position={position} > Press escape to close the drawer ); }; ``` ## Overflow Overflow is handled within the content of the drawer. The title will remain static. The `scrollableFocus` prop can be passed in to allow the scrollable body content to be focusable. ```jsx live () => { const drawer = useOverlay('overflow-drawer'); return ( {Array.from(Array(50).keys()).map((item) => { return (

Overflow Example - Scroll

); })} ); }; ``` ## closeOnClickOutside Use the `closeOnClickOutside` prop to prevent closing the drawer on outside clicks. Drawers using this prop can still be closed with the close button or through the use of state. ```jsx live () => { const drawer = useOverlay('drawer-closeOnClickOutside'); return ( Not closing on outside click ); }; ``` ## closeOnEscPress Use the `closeOnEscPress` prop to prevent closing the drawer with the Esc key. Drawers using this prop can still be closed with the close button or through the use of state. ** Accessibility Notice: The ability to close or dismiss modals and dialogs with the escape key is an absolutely fundamental requirement for accessible keyboard navigation. As such, this prop should ONLY be used temporarily when programmatically necessary, such as waiting for search results to load or for an API call to return. If the process hangs or takes more than a few seconds, then this prop should be removed, so users can choose to dismiss the modal.** ```jsx live () => { const drawer = useOverlay('drawer-closeOnEscPress'); return ( No Close on Escape Press ); }; ``` ## Drawer footer Use the `footer` prop to add a footer container to a drawer. ```jsx live () => { const drawer = useOverlay('drawer-footer'); return ( } > {Array.from(Array(30).keys()).map((item) => { return (

Drawer footer with cancel button

); })} ); }; ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ```

Drawer Accessible Example

```jsx live () => { const drawer = useOverlay('drawer-footer'); return ( } > {Array.from(Array(30).keys()).map((item) => { return (

Meaningless text to fill screen and force the creation of a scrolling region.

); })} ); }; ```

Drawer Content

The content included on the Drawer must be accessible. ```jsx live () => { const drawer = useOverlay('accessible-drawer'); return ( <> ); }; ```

Triggering Elements

Esc Override

Use the `closeOnEscPress` to prevent closing the modal on Esc key. Modals using this prop can still be closed with the close button or through use of state. ** Accessibility Notice: The ability to close or dismiss modals and dialogs with the escape key is an absolutely fundamental requirement for accessible keyboard navigation. As such, this prop should ONLY be used temporarily when programmatically necessary, such as waiting for search results to load or for an API call to return. If the process hangs or takes more than a few seconds, then this prop should be removed so users can choose to dismiss the modal.** ```jsx live () => { const modal = useOverlay('closeOnEscPress-modal'); return ( No Close on Escape Press ); }; ```

Reduced Motion

Animations and transitions that have been changed when a user has `prefers-reduced-motion` set to `reduced`: - Transition upon expand/collapse is removed --- id: drawer-menu category: Navigation title: DrawerMenu description: Used to display a menu with links in a drawer. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=50340-131217 --- ```jsx import { DrawerMenu } from '@uhg-abyss/web/ui/DrawerMenu'; ``` ```jsx render ``` ## Usage Drawer menu is used for quick navigation for the related links in the menu. Drawer menu can also be used if we need interaction for both screen content and the drawer at the same time. It can be hidden to maximize space. ```jsx live () => { const menuItems = [ { title: 'Email', href: '/web/developers/overview/', icon: , }, { title: 'Upload', href: '#', icon: , }, { title: 'About Abyss', href: '/web/about/', icon: , }, { title: 'Releases', href: '/web/releases/', icon: , }, ]; return ( ); }; ``` ## Variations - **Open**: Each item describes its destination using a text label and correspondent icon. Can be closed by clicking chevron icon. - **Closed**: When closed users can only view icons as the labels will be hidden. Closed is the default state. Can be opened by clicking hamburger menu. ```jsx live () => { const menuItems = [ { title: 'About Abyss', href: '/web/about/', icon: , }, { title: 'Releases', href: '/web/releases/', icon: , }, ]; return ( ); }; ``` ### Menu items config Use the `MenuItems` prop to pass items into the drawer menu. `item` must be an object with the following structure. As the menu item is shown as a link it's not ideal to pass both `href` and `onClick` for an item. ```jsx const MenuItems = [{ title: 'Menu Item Title', // menu item title icon: // menu item icon, href: '/path/' // path for the destination link onClick: () => { // perform action }, openNewWindow: true // to open the link in new window , }]; ``` ## Label Use `label` prop to pass custom screen reader label for drawer menu. The default value is `Menu`. ```jsx live () => { const menuItems = [ { title: 'Contact Us', href: '/web/contact-us/', icon: , openNewWindow: true, }, ]; return ( ); }; ``` ## Example ```jsx live () => { const [content, setContent] = useState( 'Home Content: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet' ); const menuItems = [ { title: 'Home', icon: , onClick: () => { setContent( 'Home Content: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet' ); }, }, { title: 'Dashboard', icon: , onClick: () => { setContent( 'Dash Board Content: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet' ); }, }, ]; return ( {content} ); }; ``` ```jsx render ``` ```jsx render ``` DrawerMenu implements Example Disclosure Navigation Menu WAI-ARIA Pattern. For icon accessibility please refer to [Icon Material](/web/ui/icon-material).

Reduced Motion

Animations and transitions that have been changed when a user has `prefers-reduced-motion` set to `reduced`: - Transition upon expand/collapse is removed ```jsx render ``` ```jsx render ``` --- id: dropdown-menu-v2 category: Content title: V2DropdownMenu description: Displays a menu triggered by a button, such as a set of actions or functions. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=12639-269 subDirectory: DropdownMenu/v2 sourceIsTS: true --- ```jsx render ``` ```jsx import { V2DropdownMenu } from '@uhg-abyss/web/ui/DropdownMenu'; ``` ## Overview The `V2DropdownMenu` component displays a menu triggered by a button, known as the Action Menu. This menu can contain various items, including action items, checkboxes, radio groups, and submenus. Each item can have an icon. ```jsx live () => { const [person, setPerson] = useState('Pedro'); const [urlsChecked, setUrlsChecked] = useState(false); const [foldersChecked, setFoldersChecked] = useState(true); const [bookmarksChecked, setBookmarksChecked] = useState(false); const [termsChecked, setTermsChecked] = useState(false); const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, }, { title: 'New Private Window', onClick: () => { console.log('Clicked New Private Window!'); }, disabled: true, }, { title: 'Home', icon: ( ), onClick: () => { console.log('Clicked Home'); }, }, { title: 'Sub menu', icon: ( ), subMenu: [ { title: 'Save As...', icon: ( ), onClick: () => { console.log('Clicked Save As'); }, }, { checkboxes: [ { label: 'Accept Terms', value: 'Accept Terms', checked: termsChecked, onChange: setTermsChecked, }, ], }, ], }, { checkboxes: [ { label: 'Show Bookmarks', value: 'Show Bookmarks', checked: bookmarksChecked, onChange: setBookmarksChecked, }, { label: 'Show Full Urls', value: 'Show Full Urls', checked: urlsChecked, onChange: setUrlsChecked, disabled: true, }, { label: 'Show Folders', value: 'Show Folders', checked: foldersChecked, onChange: setFoldersChecked, }, ], }, { label: 'Radio Group', value: person, onChange: setPerson, radios: [ { label: 'Pedro Pascal', value: 'Pedro', }, { label: 'Tom Cruise', value: 'Tom' }, { label: 'Dwayne Johnson', value: 'Dwayne', disabled: true, }, ], }, ]; return ( ); }; ``` ## Label Use the `label` prop to set the text displayed on the trigger. Alternatively, you can use the `iconOnly` prop to display only an icon without text. **Note**: To meet accessibility standards, you must still provide a `label` prop when using `iconOnly`. ```jsx live () => { const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, }, { title: 'Open New Tab', onClick: () => { console.log('Open New Tab!'); }, }, { title: 'Save As...', onClick: () => { console.log('Save As...'); }, }, ]; return ( ); }; ``` ## Outline Use the `outline` prop to control the outline of the `Dropdown` menu. The default is `true`. When setting the prop to `false`, the border radius will be removed and the component will have a flat appearance. **Note**: An `outline` should be used if the `DropdownMenu` is used on a background that does not meet the 3:1 color contrast ratio. ```jsx live () => { const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, }, { title: 'Open New Tab', onClick: () => { console.log('Open New Tab!'); }, }, { title: 'Save As...', onClick: () => { console.log('Save As...'); }, }, ]; return ( ); }; ``` ## isDisabled Use the `isDisabled` prop to disable the `DropdownMenu`. ```jsx live () => { const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, disabled: false, }, ]; return ( ); }; ``` ## isLoading Use the `isLoading` prop to place the Action Menu in a loading state. This will display a loading spinner in place of the menu items while the menu is loading. You can also provide the optional prop `loadingLabel` for additional context when the menu is in a loading state. This prop takes the form of an object, as explained in our [V2LoadingSpinner](/web/ui/loading-spinner-v2#label) documentation. ```jsx live () => { const [loading, setLoading] = useState(false); const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, }, ]; return ( setLoading(!loading)}>Trigger Loading ); }; ``` ## Menu items Use the `menuItems` prop to specify what will be displayed in the Action Menu. The prop requires an array of objects that have the following forms: ### Action item ```ts interface ActionMenuItemProps { title: string; onClick: Function; icon: ReactNode; //optional isSeparated: boolean; //optional disabled: boolean; //optional } ``` ### Checkbox ```ts interface ActionMenuCheckboxItemProps { checkboxes: Array<{ label: string; checked: bool; onChange: func; disabled: bool; //optional }>; } ``` ### Radio group ```ts interface ActionMenuRadioItemProps { label: string; value: string; onChange: Function; radios: Array<{ label: string; value: string; disabled: bool; //optional }>; } ``` ### Submenu ```ts interface ActionMenuItemGroupSubMenuItem { title: string; subMenu: ActionMenuItemGroupItem[]; // any of the above types } ``` ## Inserting icons There are three different types of icons that can be added to the `DropdownMenu`: - Use the `before` prop to insert an icon before the trigger label. - Use the `iconOnly` prop to only display an icon in the trigger button without displaying the label. - The `iconOnly` prop can be used to display only an icon in the trigger button without displaying the label. - `iconOnly` also accepts a React node, allowing you to use any custom icon component. - Use the `icon` prop in the menu items to insert icons before to the item title. While this prop accepts any React node, the examples on this page use our [IconSymbol](/web/ui/icon-symbol) component. ```jsx live () => { const menuItems = [ { title: 'Home', onClick: () => { console.log('Clicked Home'); }, icon: ( ), }, { title: 'New Window', onClick: () => { console.log('New Window!'); }, icon: ( ), }, { title: 'Open New Tab', onClick: () => { console.log('Open New Tab!'); }, icon: ( ), }, { title: 'Save As...', onClick: () => { console.log('Save As...'); }, icon: ( ), }, ]; return ( } /> } /> ); }; ``` ## onClick Use the `onClick` function on each menu item to trigger a custom function when that item is clicked. ```jsx live () => { const menuItems = [ { title: 'New Window', onClick: () => { console.log('New Window!'); }, }, { title: 'Open New Tab', onClick: () => { console.log('Open New Tab!'); }, }, { title: 'Save As...', onClick: () => { console.log('Save As...'); }, icon: ( ), disabled: true, }, ]; return ; }; ``` ## onChange Use the `onChange` function to trigger a custom function when a checkbox or a radio item is clicked. You can use this to update your checked state, among other things. ```jsx live () => { const [person, setPerson] = useState('Pedro'); const [urlsChecked, setUrlsChecked] = useState(false); const [foldersChecked, setFoldersChecked] = useState(true); const [bookmarksChecked, setBookmarksChecked] = useState(false); const [termsChecked, setTermsChecked] = useState(false); const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, }, { title: 'New Private Window', onClick: () => { console.log('Clicked New Private Window!'); }, disabled: true, }, { title: 'Home', icon: ( ), onClick: () => { console.log('Clicked Home'); }, }, { title: 'Sub menu', icon: ( ), subMenu: [ { title: 'Save As...', icon: ( ), onClick: () => { console.log('Clicked Save As'); }, }, { checkboxes: [ { label: 'Accept Terms', value: 'Accept Terms', checked: termsChecked, onChange: setTermsChecked, }, ], }, ], }, { checkboxes: [ { label: 'Show Bookmarks', value: 'Show Bookmarks', checked: bookmarksChecked, onChange: setBookmarksChecked, }, { label: 'Show Full Urls', value: 'Show Full Urls', checked: urlsChecked, onChange: setUrlsChecked, disabled: true, }, { label: 'Show Folders', value: 'Show Folders', checked: foldersChecked, onChange: setFoldersChecked, }, ], }, { label: 'Radio Group', value: person, onChange: setPerson, radios: [ { label: 'Pedro Pascal', value: 'Pedro', }, { label: 'Tom Cruise', value: 'Tom' }, { label: 'Dwayne Johnson', value: 'Dwayne', disabled: true, }, ], }, ]; return ; }; ``` ## Disabled menu items When the `disabled` flag is set to `true` on a menu item, that item cannot be interacted with. This prop applies to all item types, including action items, checkboxes, and radio groups. The item will be visually styled to indicate that it is disabled. ```jsx live () => { const [bookmarksChecked, setBookmarksChecked] = useState(false); const [urlsChecked, setUrlsChecked] = useState(true); const [person, setPerson] = useState('Tom'); const menuItems = [ { title: 'New Window', onClick: () => { console.log('New Window!'); }, disabled: true, }, { title: 'New Private Window', onClick: () => { console.log('Clicked New Private Window!'); }, }, { checkboxes: [ { label: 'Show Bookmarks', value: 'Show Bookmarks', checked: bookmarksChecked, onChange: setBookmarksChecked, disabled: true, }, { label: 'Show Full Urls', value: 'Show Full Urls', checked: urlsChecked, onChange: setUrlsChecked, }, ], }, { label: 'Radio Group', value: person, onChange: setPerson, radios: [ { label: 'Pedro Pascal', value: 'Pedro', }, { label: 'Tom Cruise', value: 'Tom' }, { label: 'Dwayne Johnson', value: 'Dwayne', disabled: true, }, ], }, ]; return ; }; ``` ## isSeparated When the `isSeparated` flag is set to `true` on a menu item, a horizontal divider will be inserted after that item. [Checkbox](#checkbox) and [radio group](#radio-group) items automatically render a divider both before and after the item, so no `isSeparated` flag is required. A divider will not be rendered before the first item or after the last item. ```jsx live () => { const [person, setPerson] = useState('Pedro'); const [urlsChecked, setUrlsChecked] = useState(false); const [foldersChecked, setFoldersChecked] = useState(true); const [bookmarksChecked, setBookmarksChecked] = useState(false); const [termsChecked, setTermsChecked] = useState(false); const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, }, { title: 'New Private Window', onClick: () => { console.log('Clicked New Private Window!'); }, disabled: true, isSeparated: true, }, { title: 'Home', icon: ( ), onClick: () => { console.log('Clicked Home'); }, }, { title: 'Sub menu', icon: ( ), subMenu: [ { title: 'Save As...', icon: ( ), onClick: () => { console.log('Clicked Save As'); }, }, { checkboxes: [ { label: 'Accept Terms', value: 'Accept Terms', checked: termsChecked, onChange: setTermsChecked, }, ], }, ], }, { checkboxes: [ { label: 'Show Bookmarks', value: 'Show Bookmarks', checked: bookmarksChecked, onChange: setBookmarksChecked, }, { label: 'Show Full Urls', value: 'Show Full Urls', checked: urlsChecked, onChange: setUrlsChecked, disabled: true, }, { label: 'Show Folders', value: 'Show Folders', checked: foldersChecked, onChange: setFoldersChecked, }, ], }, { label: 'Radio Group', value: person, onChange: setPerson, radios: [ { label: 'Pedro Pascal', value: 'Pedro', }, { label: 'Tom Cruise', value: 'Tom' }, { label: 'Dwayne Johnson', value: 'Dwayne', disabled: true, }, ], }, ]; return ; }; ``` ## onOutsideClick Use `onOutsideClick` prop to trigger a custom function when the user clicks outside an open menu. ```jsx live () => { const menuItems = [ { title: 'New Window', onClick: () => { console.log('New Window!'); }, }, { title: 'Open New Tab', onClick: () => { console.log('Open New Tab!'); }, }, { title: 'Save As...', onClick: () => { console.log('Save As...'); }, icon: ( ), disabled: true, }, ]; return ( { console.log('Custom Outside Click', e); }} /> ); }; ``` ## Dropdown open state Use the `open` and `onOpenChange` props together to control the dropdown open state. `open` is a boolean that determines whether the dropdown is open or closed, and `onOpenChange` is a function that is called when the open state changes. This allows you to manage the open state of the dropdown programmatically. ```jsx live () => { const [controlledOpen, setControlledOpen] = useState(false); const toggleOpen = (newOpenState) => { console.log('new open state', newOpenState); setControlledOpen(newOpenState); }; const menuItems = [ { title: 'New Window', onClick: () => { console.log('New Window!'); }, }, { title: 'Open New Tab', onClick: () => { console.log('Open New Tab!'); }, }, { title: 'Save As...', onClick: () => { console.log('Save As...'); }, icon: ( ), disabled: true, }, ]; return ( ); }; ``` ## Height Use the `height` prop to set a custom height for the Action Menu. The default height is `500px`. This prop accepts any valid CSS height value. ```jsx live () => { const actionButtonClick = () => { console.log('Primary Action Clicked'); }; const menuItems = [ { title: 'New Window', onClick: () => { console.log('New Window!'); }, }, { title: 'Open New Tab', onClick: () => { console.log('Open New Tab!'); }, }, { title: 'New Private Window', onClick: () => { console.log('New Private Window!'); }, }, { title: 'New Incognito Window', onClick: () => { console.log('New Incognito Window!'); }, }, { title: 'Save As...', onClick: () => { console.log('Save As...'); }, icon: ( ), }, { title: 'Save All', onClick: () => { console.log('Save All!'); }, icon: ( ), }, ]; return ( ); }; ``` ## SplitButton vs. DropdownMenu `V2DropdownMenu` is a versatile component that can be used for various menu actions, while [V2SplitButton](/web/ui/split-button-v2) is specifically designed for a button with a dropdown menu that allows users to perform an action or select from a list of options.`V2SplitButton` is more suitable when you want to combine a primary action with a secondary dropdown menu. ```jsx live () => { const actionButtonClick = () => { console.log('Primary Action Clicked'); }; const menuItems = [ { title: 'New Private Window', onClick: () => { console.log('Clicked New Private Window!'); }, }, { title: 'Save URL As...', onClick: () => { console.log('Clicked Save URL As'); }, icon: ( ), }, ]; return ( ); }; ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ```

Use for application menu settings and actions only - NOT navigation

From an accessibility and WAI-ARIA perspective, dropdown and split button menus are intended **only** for application settings and actions—**not** navigation. Unlike navigation components, these rely solely on arrow keys for making selections. When using navigation components, tabbing between links is an expected behavior. Use [V2NavMenu](/web/ui/nav-menu-v2) or other components for navigating between web pages.

WAI-ARIA implementation

This component implements several WAI-ARIA design patterns beginning with Menu Button. Nested menus are of single-menu examples from Menu Bar (using roving tabindex to manage focus movement). Radio button and checkbox option operation are based upon the Editor Menu Example. ```jsx live () => { const [bookmarksChecked, setBookmarksChecked] = useState(true); const [urlsChecked, setUrlsChecked] = useState(false); const [person, setPerson] = useState('Paul'); const menuItems = [ { title: 'New Window', icon: ( ), onClick: () => { console.log('Clicked New Window!'); }, }, { title: 'New Private Window', icon: ( ), onClick: () => { console.log('Clicked New Private Window!'); }, disabled: true, }, { title: 'Home', icon: ( ), onClick: () => { console.log('Clicked Home'); }, }, { title: 'Save options', icon: , subMenu: [ { title: 'Save', icon: ( ), onClick: () => { console.log('Clicked Save As'); }, }, { title: 'Save As...', icon: ( ), onClick: () => { console.log('Clicked Save As'); }, }, { title: 'Save to web...', icon: ( ), onClick: () => { console.log('Clicked Save to web'); }, }, ], }, { checkboxes: [ { label: 'Show Bookmarks', value: 'Show Bookmarks', checked: bookmarksChecked, onChange: setBookmarksChecked, }, { label: 'Show Full Urls', value: 'Show Full Urls', checked: urlsChecked, onChange: setUrlsChecked, }, ], }, { label: 'Favorite Beatle', value: person, onChange: setPerson, radios: [ { label: 'Pete Best', value: 'Pete', disabled: true, }, { label: 'George Harrison', value: 'George', }, { label: 'John Lennon', value: 'John', }, { label: 'Paul McCartney', value: 'Paul', }, { label: 'Ringo Starr', value: 'Ringo', }, ], }, ]; return ( ); }; ``` ```jsx render ```

Component Tokens

**Note:** Click on the token row to copy the token to your clipboard. ```jsx render ``` ```jsx render ``` --- id: dropdown-menu category: Content title: DropdownMenu description: Displays a menu triggered by a button, such as a set of actions or functions. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=9141-35044 --- ```jsx render ``` ```jsx import { DropdownMenu } from '@uhg-abyss/web/ui/DropdownMenu'; ``` ```jsx live () => { const [bookmarksChecked, setBookmarksChecked] = useState(true); const [urlsChecked, setUrlsChecked] = useState(false); const [person, setPerson] = useState('Pedro'); const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, }, { title: 'New Private Window', onClick: () => { console.log('Clicked New Private Window!'); }, disabled: true, }, { title: 'Home', icon: , onClick: () => { console.log('Clicked Home'); }, }, { title: 'Sub menu', subMenu: [ { title: 'Save As...', icon: , onClick: () => { console.log('Clicked Save As'); }, }, { checkboxes: [ { label: 'Show Full Urls', value: 'Show Full Urls', checked: urlsChecked, onChange: setUrlsChecked, }, ], }, { label: 'Radio Group', value: person, onChange: setPerson, radios: [ { label: 'Pedro Duarte', value: 'Pedro', }, { label: 'Tom Hanks', value: 'Tom' }, ], }, ], }, { checkboxes: [ { label: 'Show Bookmarks', value: 'Show Bookmarks', checked: bookmarksChecked, onChange: setBookmarksChecked, }, { label: 'Show Full Urls', value: 'Show Full Urls', checked: urlsChecked, onChange: setUrlsChecked, }, ], }, { label: 'Radio Group', value: person, onChange: setPerson, radios: [ { label: 'Pedro Duarte', value: 'Pedro', }, { label: 'Tom Hanks', value: 'Tom' }, ], }, ]; return ( } menuItems={menuItems} /> ); }; ``` ## useForm Using the `useForm` hook lets the DOM handle form data. For form usage with selections, the use of the [SelectInput](/web/ui/select-input) component is recommended. ```jsx live () => { const form = useForm({ defaultValues: { 'dropdown-menu-radios': 'Tom', 'dropdown-menu-sub-radios': 'Pedro', 'dropdown-menu-sub-checkbox': true, 'dropdown-menu-checkboxes-1': true, 'dropdown-menu-checkboxes-2': false, }, }); const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, }, { title: 'New Private Window', onClick: () => { console.log('Clicked New Private Window!'); }, disabled: true, }, { title: 'Home', icon: , onClick: () => { console.log('Clicked Home'); }, }, { title: 'Sub menu', subMenu: [ { title: 'Save As...', icon: , onClick: () => { console.log('Clicked Save As'); }, }, { checkboxes: [ { model: 'dropdown-menu-sub-checkbox', label: 'Show Full Urls', value: 'Show Full Urls', }, ], }, { model: 'dropdown-menu-sub-radios', label: 'Radio Group', radios: [ { label: 'Pedro Duarte', value: 'Pedro', }, { label: 'Tom Hanks', value: 'Tom' }, ], }, ], }, { checkboxes: [ { model: 'dropdown-menu-checkboxes-1', label: 'Show Bookmarks', value: 'Show Bookmarks', }, { model: 'dropdown-menu-checkboxes-2', label: 'Show Full Urls', value: 'Show Full Urls', }, ], }, { label: 'Radio Group', model: 'dropdown-menu-radios', radios: [ { label: 'Pedro Duarte', value: 'Pedro', }, { label: 'Tom Hanks', value: 'Tom' }, ], }, ]; return ( } menuItems={menuItems} /> ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [bookmarksChecked, setBookmarksChecked] = useState(true); const [urlsChecked, setUrlsChecked] = useState(false); const [person, setPerson] = useState('Pedro'); const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, }, { title: 'New Private Window', onClick: () => { console.log('Clicked New Private Window!'); }, disabled: true, }, { title: 'Home', icon: , onClick: () => { console.log('Clicked Home'); }, }, { title: 'Sub menu', subMenu: [ { title: 'Save As...', icon: , onClick: () => { console.log('Clicked Save As'); }, }, { checkboxes: [ { label: 'Show Full Urls', value: 'Show Full Urls', checked: urlsChecked, onChange: setUrlsChecked, }, ], }, { label: 'Radio Group', value: person, onChange: setPerson, radios: [ { label: 'Pedro Duarte', value: 'Pedro', }, { label: 'Tom Hanks', value: 'Tom' }, ], }, ], }, { checkboxes: [ { label: 'Show Bookmarks', value: 'Show Bookmarks', checked: bookmarksChecked, onChange: setBookmarksChecked, }, { label: 'Show Full Urls', value: 'Show Full Urls', checked: urlsChecked, onChange: setUrlsChecked, }, ], }, { label: 'Radio Group', value: person, onChange: setPerson, radios: [ { label: 'Pedro Duarte', value: 'Pedro', }, { label: 'Tom Hanks', value: 'Tom' }, ], }, ]; return ( } menuItems={menuItems} /> ); }; ``` ## Label Use the `label` prop to insert text or icon elements into the Dropdown menu button. You can use the `hideLabel` prop to hide the label if you are using icons only. `label` is required. ```jsx live () => { const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, }, { title: 'Open New Tab', onClick: () => { console.log('Open New Tab!'); }, }, { title: 'Save As...', onClick: () => { console.log('Save As...'); }, icon: , }, ]; const customIcon = ( ); return ( } menuItems={menuItems} /> {customIcon}} menuItems={menuItems} /> ); }; ``` ## Inserting icons Insert icons into the Dropdown menu button using the `before` and `after` props. ```jsx live () => { const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, }, { title: 'Open New Tab', onClick: () => { console.log('Open New Tab!'); }, }, { title: 'Save As...', onClick: () => { console.log('Save As...'); }, icon: , }, ]; return ( } menuItems={menuItems} /> } menuItems={menuItems} /> } after={} menuItems={menuItems} /> } after={} menuItems={menuItems} /> ); }; ``` ## Outline Use the `outline` prop to turn on the outline of the Dropdown menu. The default is `false`. _**Note**_: An `outline` should be added if the Dropdown menu is used on a background that does not meet the 3:1 color contrast ratio. ```jsx live () => { const [bookmarksChecked, setBookmarksChecked] = useState(true); const [urlsChecked, setUrlsChecked] = useState(false); const [person, setPerson] = useState('Pedro'); const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, disabled: false, }, { title: 'New Private Window', onClick: () => { console.log('Clicked New Private Window!'); }, disabled: true, }, { title: 'Home', icon: , onClick: () => { console.log('Clicked Home'); }, isSeparated: true, }, { title: 'Sub menu', subMenu: [ { title: 'Save As...', icon: , onClick: () => { console.log('Clicked Save As'); }, }, { checkboxes: [ { label: 'Show Full Urls', value: 'Show Full Urls', checked: urlsChecked, onChange: setUrlsChecked, }, ], }, ], }, { checkboxes: [ { label: 'Show Bookmarks', value: 'Show Bookmarks', checked: bookmarksChecked, onChange: setBookmarksChecked, }, { label: 'Show Full Urls', value: 'Show Full Urls', checked: urlsChecked, onChange: setUrlsChecked, }, ], }, { label: 'Radio Group', value: person, onChange: setPerson, radios: [ { label: 'Pedro Duarte', value: 'Pedro' }, { label: 'Tom Hanks', value: 'Tom' }, ], }, ]; return ( } menuItems={menuItems} /> } menuItems={menuItems} /> ); }; ``` ## Variant Use the `variant` prop to change the visual style of the Dropdown menu. You can set the value to `default` or `filled`. The default value is `default`. ```jsx live () => { const [bookmarksChecked, setBookmarksChecked] = useState(true); const [urlsChecked, setUrlsChecked] = useState(false); const [person, setPerson] = useState('Pedro'); const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, disabled: false, }, { title: 'New Private Window', onClick: () => { console.log('Clicked New Private Window!'); }, disabled: true, }, { title: 'Home', icon: , onClick: () => { console.log('Clicked Home'); }, isSeparated: true, }, { title: 'Sub menu', subMenu: [ { title: 'Save As...', icon: , onClick: () => { console.log('Clicked Save As'); }, }, { checkboxes: [ { label: 'Show Full Urls', value: 'Show Full Urls', checked: urlsChecked, onChange: setUrlsChecked, }, ], }, ], }, { checkboxes: [ { label: 'Show Bookmarks', value: 'Show Bookmarks', checked: bookmarksChecked, onChange: setBookmarksChecked, }, { label: 'Show Full Urls', value: 'Show Full Urls', checked: urlsChecked, onChange: setUrlsChecked, }, ], }, { label: 'Radio Group', value: person, onChange: setPerson, radios: [ { label: 'Pedro Duarte', value: 'Pedro' }, { label: 'Tom Hanks', value: 'Tom' }, ], }, ]; return ( } menuItems={menuItems} /> } menuItems={menuItems} /> ); }; ``` ## isDisabled Use the `isDisabled` prop to disable the Dropdown menu. ```jsx live () => { const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, disabled: false, }, { title: 'New Private Window', onClick: () => { console.log('Clicked New Private Window!'); }, disabled: true, }, { title: 'Home', icon: , onClick: () => { console.log('Clicked Home'); }, }, ]; return ( } menuItems={menuItems} isDisabled /> ); }; ``` ## Menu items Use the `menuItems` prop to specify what will be displayed in the Dropdown. The prop requires an array of objects that have the following form for each item types: 1. **Action Item:** ```js { title: string, icon: node, //optional onClick: func, } ```
2. **Checkboxes:** ```js { checkboxes: Array, } // Checkbox item checkboxes: [ { label: string, value: string, checked: bool, // useState onChange: func, // useState model: string, // useForm }, ]; ```
3. **Radio-Group:** ```js { label: string, value: string, // useState onChange: func, // useState model: string, // useForm radios: Array, } // Radio item radios: [ { label: string, value: string, } ] ```
4. **Sub-Menu:** ```js { title: string, subMenu: Array, } // Sub-menu subMenu: [ { Radio-Group Checkboxes Action Item Sub-Menu } ] ``` ## onClick Use the `onClick` function to trigger a custom function when the menu item is clicked. ```jsx live () => { const menuItems = [ { title: 'New Window', onClick: () => { console.log('New Window!'); }, }, { title: 'Open New Tab', onClick: () => { console.log('Open New Tab!'); }, }, { title: 'Save As...', onClick: () => { console.log('Save As...'); }, icon: , disabled: true, }, ]; return ( } /> ); }; ``` ## onChange Use the `onChange` function to trigger a custom function when a checkbox or a radio item is clicked. You can use this to update your checked state, among other things. ```jsx live () => { const [bookmarksChecked, setBookmarksChecked] = useState(true); const [urlsChecked, setUrlsChecked] = useState(false); const [person, setPerson] = useState('Pedro'); const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, isSeparated: true, }, { title: 'New Private Window', onClick: () => { console.log('Clicked New Private Window!'); }, disabled: true, }, { title: 'Home', icon: , onClick: () => { console.log('Clicked Home'); }, isSeparated: true, }, { title: 'Sub menu', subMenu: [ { title: 'Save As...', icon: , onClick: () => { console.log('Clicked Save As'); }, }, { checkboxes: [ { label: 'Show Full Urls', value: 'Show Full Urls', checked: urlsChecked, onChange: setUrlsChecked, }, ], }, ], }, { checkboxes: [ { label: 'Show Bookmarks', value: 'Show Bookmarks', checked: bookmarksChecked, onChange: setBookmarksChecked, }, { label: 'Show Full Urls', value: 'Show Full Urls', checked: urlsChecked, onChange: setUrlsChecked, }, ], }, { label: 'Radio Group', value: person, onChange: setPerson, radios: [ { label: 'Pedro Duarte', value: 'Pedro' }, { label: 'Tom Hanks', value: 'Tom' }, ], }, ]; return ( } /> ); }; ``` ## Disabled menu items When `disabled` flag is **true**, it prevents the user from interacting with the menu item. ```jsx live () => { const menuItems = [ { title: 'New Window', onClick: () => { console.log('New Window!'); }, }, { title: 'Open New Tab', onClick: () => { console.log('Open New Tab!'); }, }, { title: 'Save As...', onClick: () => { console.log('Save As...'); }, icon: , disabled: true, }, ]; return ( } /> ); }; ``` ## isSeparated When `isSeparated` flag is **true**, it renders a horizontal divider that separates the menu item. The _checkbox_ and _radio_ group automatically render a divider before and after the item, so no `isSeparated` flag is required for checkboxes and radio items. Divider is not rendered before and after the first and last item, respectively. ```jsx live () => { const [bookmarksChecked, setBookmarksChecked] = useState(true); const [urlsChecked, setUrlsChecked] = useState(false); const [person, setPerson] = useState('Pedro'); const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, isSeparated: true, }, { title: 'New Private Window', onClick: () => { console.log('Clicked New Private Window!'); }, disabled: true, }, { title: 'Home', icon: , onClick: () => { console.log('Clicked Home'); }, isSeparated: true, }, { title: 'Sub menu', subMenu: [ { title: 'Save As...', icon: , onClick: () => { console.log('Clicked Save As'); }, }, { checkboxes: [ { label: 'Show Full Urls', value: 'Show Full Urls', checked: urlsChecked, onChange: setUrlsChecked, }, ], }, ], }, { checkboxes: [ { label: 'Show Bookmarks', value: 'Show Bookmarks', checked: bookmarksChecked, onChange: setBookmarksChecked, }, { label: 'Show Full Urls', value: 'Show Full Urls', checked: urlsChecked, onChange: setUrlsChecked, }, ], }, { label: 'Radio Group', value: person, onChange: setPerson, radios: [ { label: 'Pedro Duarte', value: 'Pedro' }, { label: 'Tom Hanks', value: 'Tom' }, ], }, ]; return ( } /> ); }; ``` ## onOutsideClick Use `onOutsideClick` prop to trigger a custom function when the user clicks outside of an open menu. ```jsx live () => { const menuItems = [ { title: 'option', onClick: () => { console.log('Clicked Option'); }, }, ]; return ( { console.log('Custom Outside Click', e); }} /> ); }; ``` ## open & onOpenChange Use the combination of the `open` and `onOpenChange` props together to control the handling of the dropdown open state. ```jsx live () => { const [controlledOpen, setControlledOpen] = useState(false); const toggleOpen = (newOpenState) => { console.log('new open state', newOpenState); setControlledOpen(newOpenState); }; const menuItems = [ { title: 'option', onClick: () => { console.log('Clicked Option'); }, }, ]; return ( ); }; ``` ```jsx render ``` ```jsx render ``` Adheres to the Menu Button WAI-ARIA design pattern. When using nested dropdown menus, adheres more to a single-menu example of the Menu Bar WAI-ARIA design pattern. Uses roving tabindex to manage focus movement among menu items. The Editor Menu Example demonstrates selected menu options such as radio buttons and checkboxes. The Navigation Menubar Example demonstrates submenus. ```jsx live () => { const [bookmarksChecked, setBookmarksChecked] = useState(true); const [urlsChecked, setUrlsChecked] = useState(false); const [person, setPerson] = useState('Pedro'); const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, }, { title: 'New Private Window', onClick: () => { console.log('Clicked New Private Window!'); }, disabled: true, }, { title: 'Home', icon: , onClick: () => { console.log('Clicked Home'); }, }, { title: 'Sub menu', subMenu: [ { title: 'Save As...', icon: , onClick: () => { console.log('Clicked Save As'); }, }, { checkboxes: [ { label: 'Show Full Urls', value: 'Show Full Urls', checked: urlsChecked, onChange: setUrlsChecked, }, ], }, { label: 'Radio Group', value: person, onChange: setPerson, radios: [ { label: 'Pedro Duarte', value: 'Pedro', }, { label: 'Tom Hanks', value: 'Tom' }, ], }, ], }, { checkboxes: [ { label: 'Show Bookmarks', value: 'Show Bookmarks', checked: bookmarksChecked, onChange: setBookmarksChecked, }, { label: 'Show Full Urls', value: 'Show Full Urls', checked: urlsChecked, onChange: setUrlsChecked, }, ], }, { label: 'Radio Group', value: person, onChange: setPerson, radios: [ { label: 'Pedro Duarte', value: 'Pedro', }, { label: 'Tom Hanks', value: 'Tom' }, ], }, ]; return ( } menuItems={menuItems} /> ); }; ``` ```jsx render ``` --- id: emphasis-banner-v2 category: Content title: V2EmphasisBanner description: Displays a banner to emphasize important information design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=10572-6369 subDirectory: EmphasisBanner sourceIsTS: true --- ```jsx import { V2EmphasisBanner } from '@uhg-abyss/web/ui/EmphasisBanner'; ``` ```jsx sandbox { component: 'V2EmphasisBanner', inputs: [ { prop: 'children', type: 'string', }, { prop: 'title', type: 'string', }, { prop: 'color', type: 'select', options: [ { label: 'Emphasis 1', value: 'emphasis1' }, { label: 'Emphasis 2', value: 'emphasis2' }, { label: 'Emphasis 3', value: 'emphasis3' }, { label: 'Emphasis 4', value: 'emphasis4' }, ], }, { prop: 'dismissible', type: 'boolean', }, ], } () => { return ( Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. ); }; ``` ## Title Use the `title` prop to set the title of the Emphasis Banner. By default, the title is rendered as an `

`, but this can be configured using the `headingLevel` prop. ```jsx live () => { const focusTargetRef = useRef(null); return ( Focus target { focusTargetRef.current?.focus(); }} > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. { focusTargetRef.current?.focus(); }} > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. ); }; ``` ## Content ### Text content The children of the Emphasis Banner will be displayed as the main content. The content can only be a string and is limited to 100 characters in length. ```jsx live () => { const focusTargetRef = useRef(null); return ( Focus target { focusTargetRef.current?.focus(); }} > Text is placed here. ); }; ``` ### Custom content Use the `customContent` prop to add custom content below the main text content. This prop accepts any valid `ReactNode`. ```jsx live () => { const CustomContentWrapper = styled('div', { display: 'flex', flexDirection: 'row', }); const focusTargetRef = useRef(null); return ( Focus target { focusTargetRef.current?.focus(); }} customContent={ Custom link } > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. ); }; ``` ## Color Use the `color` prop to set the color of the Emphasis Banner. The available options are `'emphasis1'`, `'emphasis2'`, `'emphasis3'`, and `'emphasis4'`. ```jsx live () => { const focusTargetRef = useRef(null); return ( Focus target { focusTargetRef.current?.focus(); }} > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. { focusTargetRef.current?.focus(); }} > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. { focusTargetRef.current?.focus(); }} > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. { focusTargetRef.current?.focus(); }} > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. ); }; ``` ## Brand icon Use the `iconBrand` prop to add an [IconBrand](/web/brand/uhc/icon-brand) to the Emphasis Banner. The `iconBrand` prop accepts an object of most props of the IconBrand component, except `size`, which is set by the Emphasis Banner and cannot be altered. ```jsx live () => { const focusTargetRef = useRef(null); return ( Focus target { focusTargetRef.current?.focus(); }} > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. { focusTargetRef.current?.focus(); }} > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. ); }; ``` ## CTA Use the `cta` prop to add a call-to-action to the Emphasis Banner. The `cta` prop accepts an object with the following structure: ```ts { primaryButton?: V2ButtonProps; secondaryButton?: V2ButtonProps; link?: V2LinkProps; } ``` Rules for cta: - `primaryButton`: A primary button must always be used with a secondary button and cannot be used alone. - `secondaryButton`: A secondary button can be used alone, but not with a link. - `link`: If a link is provided, it is exclusive and cannot be used with a primary button or secondary button. `V2ButtonProps` and `V2LinkProps` are objects that accept most props of the [V2Button](/web/ui/button-v2) and [V2Link](/web/ui/link-v2) components, respectively, except for `size`, which is set by the Emphasis Banner and cannot be altered. ```jsx live () => { const focusTargetRef = useRef(null); return ( Focus target { console.log('Link clicked'); }, }, }} onClose={() => { focusTargetRef.current?.focus(); }} > Lorem ipsum dolor sit amet, consectetur adipiscing elit. { console.log('Secondary button clicked'); }, }, }} onClose={() => { focusTargetRef.current?.focus(); }} > Vestibulum fringilla mollis duis rhoncus ipsum. { console.log('Primary button clicked'); }, }, secondaryButton: { children: 'Secondary', onClick: () => { console.log('Secondary button clicked'); }, }, }} onClose={() => { focusTargetRef.current?.focus(); }} > Lorem ipsum dolor sit amet, consectetur adipiscing elit. ); }; ``` ## Dismissible Use the `dismissible` prop to control whether the Emphasis Banner can be closed. The default value is `true`. ```jsx live () => { const focusTargetRef = useRef(null); return ( Focus target { focusTargetRef.current?.focus(); }} > This Emphasis Banner can be dismissed. This Emphasis Banner cannot be dismissed. ); }; ``` ### onClose Use the `onClose` prop to execute a custom callback when the Emphasis Banner is closed. Note: `onClose` is only used when `dismissible` is `true`. ```jsx live () => { const focusTargetRef = useRef(null); return ( Focus target { focusTargetRef.current?.focus(); }} > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. ); }; ``` ## Responsiveness On screens less than 744px wide, the Emphasis Banner will adjust its layout. Resize the window to see the change! ```jsx live () => { const focusTargetRef = useRef(null); return ( Focus target { console.log('Secondary button clicked'); }, }, }} onClose={() => { focusTargetRef.current?.focus(); }} > Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis. ); }; ``` ```jsx render ``` ```jsx render ``` ```jsx live () => { const focusTargetRef = useRef(null); return ( Focus target { console.log('Secondary button clicked'); }, }, }} onClose={() => { focusTargetRef.current?.focus(); }} > Accessibility is built into the new V2EmphasisBanner component. Be sure to define all props if they communicate information. ); }; ``` ```jsx render ```
Decorative Icons
The brand icon in the Emphasis Banner is considered decorative and does not require a text alternative, though one can be provided if desired.
Close Button Guidance
If the close button is present—which it is by default—it must be keyboard accessible. A keyboard-only user must be able to tab to the button, and activate it with the space bar and the enter key. When the Emphasis Banner is closed, focus must be placed back where it previously was on the page.
Component Tokens
Note: Click on the token row to copy the token to your clipboard. ```jsx render ``` --- id: file-upload category: Forms title: FileUpload description: An HTML5 file upload component with a drag-drop zone and file browser for selection. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=8207-26355 --- ```jsx import { FileUpload } from '@uhg-abyss/web/ui/FileUpload'; ``` ```jsx sandbox { component: 'FileUpload', inputs: [ { prop: 'maxFiles', type: 'number', }, { prop: 'maxFileSize', type: 'number', }, { prop: 'uploadMessage', type: 'string', }, { prop: 'maxMessage', type: 'string', }, { prop: 'noIcon', type: 'boolean', }, { prop: 'isUploading', type: 'boolean', }, { prop: 'isDisabled', type: 'boolean', }, { prop: 'dragDisabled', type: 'boolean', }, { prop: 'label', type: 'string', }, { prop: 'hideLabel', type: 'boolean', }, ], } () => { const [fileList, setFileList] = useState([]) console.log('fileList', fileList) return ( ); }; ``` ## Usage To add one or more files to the file upload queue either click the "Open File Browser" button or drag and drop onto the drop zone. Each time a file or group of files is added to the queue the `onChange` callback returns the current array of file objects that are ready to be uploaded. Each file is returned as a File type object that contains the following properties: `name`, `path`, `lastModified`, `lastModifiedDate`, `size`, `type` and `webkitRelativePath`. For more info on these properties please visit [here](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#getting_information_on_selected_files). To access the contents of the file and complete the upload process you must use the [FileReader API](https://developer.mozilla.org/en-US/docs/Web/API/FileReader). For accessibility compliance and benefit of the user experience, upon completion of file upload it is recommended that some form of feedback is utilized to inform the user of the upload status such as through the usage of the Abyss [Alert](/web/ui/alert) component. Use the example below to add files and submit to see a complete usage cycle. ```jsx live () => { const [fileHistoryList, setFileHistoryList] = useState([]); const [isUploading, setIsUploading] = useState(false); const [alertIsVisible, setAlertIsVisible] = useState(false); const form = useForm(); const onSubmit = (data) => { console.log('data', data); const fileList = data['fileUpload']; if (!fileList.length) return; setAlertIsVisible(false); setIsUploading(true); const fileHistory = fileList.map((file) => { return { name: file.name, complete: true, }; }); setTimeout(() => { form.reset(); setFileHistoryList(fileHistory); setIsUploading(false); setAlertIsVisible(true); }, 2000); }; return ( ); }; ``` ## useForm (recommended) Using the `useForm` hook lets the DOM handle form data. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( ); }; ``` ## useState Using the `useState` hook gets values from the component state. ### Controlled To control the state of the file upload queue use the `value` prop in combination with `onChange`. This is recommended if you ever need to clear and/or programmatically remove individual items from the queue. ```jsx live () => { const [fileList, setFileList] = useState([]); const onSubmit = () => { console.log('fileList', fileList); }; return ( ); }; ``` ### Uncontrolled By default state will be managed internally by the component. Please note that the only way to remove items from the file upload queue will be by clicking the 'X' button located on the right side of each file item. ```jsx live () => { const [fileList, setFileList] = useState([]); const onSubmit = () => { console.log('fileList', fileList); }; return ( ); }; ``` ## File tray FileUpload comes equipped with a basic file tray UI that is internally managed by the component. Prior to submission any file that has been added to the file tray upload queue can be removed by clicking the 'X' button located on the right side of each file item. If you'd like to use a separate component for the file tray utilize the `removeFileTray` prop to remove the built-in tray and see the [DataTable Example](#datatable-example) below for an example on how to incorporate usage of the [DataTable](/web/ui/data-table) component. ```jsx live () => { const [fileHistoryList, setFileHistoryList] = useState([]); const [isUploading, setIsUploading] = useState(false); const [alertIsVisible, setAlertIsVisible] = useState(false); const form = useForm(); const onSubmit = (data) => { console.log('data', data); const fileList = data['fileUpload']; if (!fileList.length) return; setAlertIsVisible(false); setIsUploading(true); const fileHistory = fileList.map((file) => { return { name: file.name, complete: true, }; }); setTimeout(() => { form.reset(); setFileHistoryList(fileHistory); setIsUploading(false); setAlertIsVisible(true); }, 2000); }; return ( ); }; ``` ## Upload message Use the `uploadMessage` prop to configure the messaging that displays beneath the file upload icon. The recommended usage of this is for displaying more detailed information on the file types allowed as seen in this example. For adding file type validation please see the [File Types](#file-types) section below. ```jsx live () => { const form = useForm(); return ( ); }; ``` ## Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip) or a [Popover](/web/ui/popover). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live () => { const form = useForm(); return ( } maxFileSize={5} model="helper-custom" validators={{ required: true }} /> ); }; ``` ## Header Add an optional header to provide the user with more detailed information and guidance on the prescribed usage of the component. Using the `headerContent` prop pass in the heading title text using `FileUpload.Heading` and the description text using `FileUpload.Description`. ```jsx live () => { const form = useForm(); const headerContent = ( Accepted Files JPEG (Joint Photographic Experts Group), PNG (Portable Network Graphics), GIF (Graphics Interchange Format), PDF (Portable Document Format), SVG (Scalable Vector Graphics), MP4 (Moving Picture Experts Group) ); return ( ); }; ``` ## Uploading spinner To show an upload-in-progress state set the `isUploading` prop to `true` and the "Open File Browser" button will be replaced with a loading spinner. ```jsx live () => { const form = useForm(); return ( ); }; ``` ## Max files Use the `maxFiles` prop to set the maximum number of files that can added to the file upload queue. When set to `1` the component is operating in single file mode. The default setting is `0` which allows for the addition of unlimited files. ```jsx live () => { const form = useForm(); return ( ); }; ``` ## Max file size Use the `maxFileSize` prop to limit the maximum file size allowed in MB (megabytes). If a file is selected that exceeds the file size limit it will be not be added to the file upload queue and an error message will be displayed. The default setting has no file size limitation. File size details are displayed beneath the "Open File Browser" button. ```jsx live () => { const form = useForm(); return ( ); }; ``` ## Disabled Set the `isDisabled` prop to `true` to disable the file upload field so no files can be dragged onto the drop zone or selected through the file browser. ```jsx live () => { const form = useForm(); return ( ); }; ``` ## Disable drag and drop Use the `dragDisabled` prop to disable the drag and drop functionality. When disabled the file browser must be utilized for adding files. ```jsx live () => { const form = useForm(); return ( ); }; ``` ## File history To include previously uploaded files within the file tray pass in an array of objects to the `fileHistory` prop. Each file history object must include the following two properties: - `complete` : boolean that determines the file's current status displayed as a badge - `name` : file name that will be displayed for the item Use the `fileHistorySort` prop to determine the sort direction of file history items. If set to `desc` file history items will remain below all newly added files. If set to `asc` all file history items will remain on top. The default setting is `asc`. ```jsx live () => { const form = useForm(); const fileHistoryList = [ { complete: true, name: 'file-status-is-complete.jpg', }, { complete: false, name: 'file-status-is-incomplete.jpg', }, ]; return ( ); }; ``` ## File types Use the `fileTypes` prop to pass in an object of accepted file types. The value must be an object with a common [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) as keys and an array of file extensions as values. Any files added which aren't accepted will trigger the built in file type error validation. ```jsx live () => { const form = useForm(); const fileTypesAccepted = { 'image/jpeg': ['.jpg'], 'image/png': ['.png'], }; const headerContent = ( Accepted File Type JPEG (Joint Photographic Experts Group), PNG (Portable Network Graphics) ); return ( ); }; ``` ## Custom validation Use the `customValidation` prop to supply a custom function for handling additional validation. This function will be called each time a file or set of files are dragged onto the drop zone or selected from the file browser. When called a single argument will be supplied containing all files added with each file as a File type object that includes the following properties: `name`, `path`, `lastModified`, `lastModifiedDate`, `size`, `type` and `webkitRelativePath`. To display an error message return an object with a `message` property containing the message content you'd like displayed. If you'd like validate more than one error per file you can return an array of error message objects. ```jsx live () => { const form = useForm(); const headerContent = ( File Restrictions File name must not be larger than 10 characters. ); const validate = (file) => { if (file.name && file.name.length > 10) { return { message: `Name is larger than 10 characters`, }; } return null; }; return ( ); }; ``` ## DataTable example Utilizing the [DataTable](/web/ui/data-table) as your file tray UI will require more initial set up but in exchange provides the power and flexibility of the DataTable to customize the display and management of all your file data needs. Please see the example below for assistance with implementation. Please Note: - To remove the built-in file tray and incorporate DataTable you will need to add the `removeFileTray` prop. - Any removal or change in state of files in the DataTable will need to be reflected in the state of FileUpload in order for file validation to remain accurate. - In the example below the state of uploaded/existing files is held separately outside of the FileUpload component. If you choose to incorporate these files into the FileUpload component they will need to be converted to File objects. ```jsx live () => { const existingFilesData = [ { date: '01/01/2023', name: 'Existing File.png', status: 'Complete', docType: 'claim', uploaded: true, }, ]; const docTypeOptions = [ { value: 'contract', label: 'Contract' }, { value: 'schedule', label: 'Fee Schedule' }, { value: 'claim', label: 'Claim Details' }, ]; const [fileHistoryList, setFileHistoryList] = useState(existingFilesData); const [isUploading, setIsUploading] = useState(false); const [alertIsVisible, setAlertIsVisible] = useState(false); const form = useForm(); const currentFiles = form.watch('fileUpload'); const columns = React.useMemo( () => [ { Header: 'Date', accessor: 'date', }, { Header: 'File name', accessor: 'name', sortType: 'alphanumericCaseInsensitive', }, { Header: 'Doc Type', accessor: 'docType', Cell: ({ value, cellActions, row }) => { const uploaded = row.original && row.original.uploaded; return !uploaded ? ( { cellActions.modifyRow(row, { docType: val }); }} /> ) : ( docTypeOptions.find((option) => option.value === value).label ); }, }, { Header: 'Status', accessor: 'status', Cell: ({ value }) => { let badgeValues = { badgeLabel: '', variant: '', }; switch (value) { case 'Complete': badgeValues = { badgeLabel: value, variant: 'success', }; break; default: badgeValues = { badgeLabel: 'Pending Upload', variant: 'warning', }; break; } const { badgeLabel, variant } = badgeValues; return {badgeLabel}; }, }, ], [] ); const deleteButton = { onClick: ({ row, deleteRow }) => { const filteredFiles = currentFiles.filter((_, index) => { return index !== row.original.id; }); form.setValue('fileUpload', filteredFiles); }, checkDisabled: (row) => { return row.original.uploaded; }, label: 'Delete', }; const tableData = useDataTable({ initialData: existingFilesData, initialColumns: columns, showPagination: false, individualActions: deleteButton, noDataMessage: 'Add files for upload', }); const onSubmit = () => { const filesToBeUploaded = tableData.data.filter((row) => !row.uploaded); setAlertIsVisible(false); setIsUploading(true); setTimeout(() => { form.reset(); const fileHistory = filesToBeUploaded.map((file) => { return { ...file, date: dayjs().format('MM/DD/YYYY'), status: 'Complete', uploaded: true, }; }); setFileHistoryList((prev) => [...prev, ...fileHistory]); setIsUploading(false); setAlertIsVisible(true); }, 2000); }; useEffect(() => { if (!currentFiles || !Array.isArray(currentFiles)) return; const currentFilesMapped = currentFiles.map((file, index) => { return { file, name: file.name, date: 'MM/DD/YYYY', uploaded: false, docType: 'claim', id: index, }; }); const filesToUpdate = [...fileHistoryList, ...currentFilesMapped]; tableData.setData(filesToUpdate); }, [currentFiles, fileHistoryList]); return ( ); }; ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx live () => { const form = useForm(); const [fileHistoryList, setFileHistoryList] = useState([]); const [isUploading, setIsUploading] = useState(false); const [alertIsVisible, setAlertIsVisible] = useState(false); const fileTypesAccepted = { 'image/jpeg': ['.jpg'], 'image/png': ['.png'], }; const headerContent = ( File requirements Allowed types: JPEG, PNG Max file name length: 20 characters ); const validate = (file) => { if (file.name && file.name.length > 20) { return { message: `Name is larger than 20 characters`, }; } return null; }; const onSubmit = (data) => { console.log('data', data); const fileList = data['fileUpload']; if (!fileList.length) return; setAlertIsVisible(false); setIsUploading(true); const fileHistory = fileList.map((file) => { return { name: file.name, complete: true, }; }); setTimeout(() => { form.reset(); setFileHistoryList(fileHistory); setIsUploading(false); setAlertIsVisible(true); }, 2000); }; return ( } maxFileSize={5} maxFiles={3} headerContent={headerContent} fileTypes={fileTypesAccepted} uploadMessage="Drag JPG or PNG file here" instructionText="Drag files here" validators={{ required: true }} customValidation={validate} /> ); }; ``` --- id: flex category: Layout title: Flex description: Used to incorporate CSS Flexbox into UI layouts. --- ```jsx import { Flex } from '@uhg-abyss/web/ui/Flex'; ``` ```jsx sandbox { component: 'Flex', inputs: [ { prop: 'justify', type: 'select', options: [ { label: 'Default', value: '' }, { label: 'flex-start', value: 'flex-start' }, { label: 'flex-end', value: 'flex-end' }, { label: 'center', value: 'center' }, { label: 'space-between', value: 'space-between' }, { label: 'space-around', value: 'space-around' }, { label: 'space-evenly', value: 'space-evenly' }, { label: 'start', value: 'start' }, { label: 'end', value: 'end' }, { label: 'left', value: 'left' }, { label: 'right', value: 'right' }, ], }, { prop: 'alignItems', type: 'select', options: [ { label: 'Default', value: '' }, { label: 'stretch', value: 'stretch' }, { label: 'flex-start', value: 'flex-start' }, { label: 'flex-end', value: 'flex-end' }, { label: 'center', value: 'center' }, { label: 'baseline', value: 'baseline' }, { label: 'first baseline', value: 'first baseline' }, { label: 'last baseline', value: 'last baseline' }, { label: 'start', value: 'start' }, { label: 'end', value: 'end' }, { label: 'self-start', value: 'self-start' }, { label: 'self-end', value: 'self-end' }, ], }, { prop: 'alignContent', type: 'select', options: [ { label: 'Default', value: '' }, { label: 'flex-start', value: 'flex-start' }, { label: 'flex-end', value: 'flex-end' }, { label: 'center', value: 'center' }, ], }, { prop: 'direction', type: 'select', options: [ { label: 'Default', value: '' }, { label: 'row', value: 'row' }, { label: 'row-reverse', value: 'row-reverse' }, { label: 'column', value: 'column' }, { label: 'column-reverse', value: 'column-reverse' }, ] }, ], }
Flex Start

Flex Start

Flex Start
``` ## Justify Flexbox justify-content css property. Use the `justify` prop to define the alignment along the main axis. Types include: `'flex-start'`, `'flex-end'`, `'center'`, `'space-between'`, `'space-around'`, `'space-evenly'`, `'start'`, `'end'`, `'left'`, `'right'`. ```jsx live
Flex Start

Flex Start

Flex Start

Center

Center

Center

Flex End{' '}

Flex End{' '}

Flex End{' '}

Space Between

Space Between

Space Between

Space Around

Space Around

Space Around

Space Evenly

Space Evenly

Space Evenly
``` ## alignItems Flexbox align-items css property. Use the `alignItems` prop to define the default behavior for how flex items are laid out along the cross axis on the current line. Types include: `'stretch'`, `'flex-start'`, `'flex-end'`, `'center'`, and `'baseline'`. ```jsx live
Flex Start

Flex Start

Flex Start

Center

Center

Center

Flex End

Flex End

Flex End

Stretch

Stretch

Stretch

Baseline

Baseline

Baseline
``` ## alignContent Use the `alignContent` prop to orient horizontal location of columns. Types include: `'stretch'`, `'flex-start'`, `'flex-end'`, `'center'`, and `'space-between'`, and `'space-around'`. ```jsx live
Flex Start

Flex Start

Flex Start

Flex End

Flex End

Flex End

Center

Center

Center

Stretch

Stretch

Stretch
``` ## Direction Flexbox flex-direction css property. Use the `direction` prop to establish the main-axis, thus defining the direction flex items are placed in the flex container. Types include: `'row'`, `'row-reverse'`, `'column'`, `'column-reverse'`. ```jsx live
Flex Row 1

Flex Row 2

Flex Row 3

Flex Column 1

Flex Column 2

Flex Column 3
``` ```jsx render ``` ```jsx render ``` ```jsx render ``` ```jsx render ``` --- id: floating-section category: Layout title: FloatingSection description: Used to create a floating sticky container. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=20298-77414 --- ```jsx import { FloatingSection } from '@uhg-abyss/web/ui/FloatingSection'; ``` ```jsx render ``` ## Overview The `FloatingSection` component creates a floating sticky container on the screen that maintains continuous visible access to its content while navigating through its parent container. The primary usage is for housing form controls to maintain visible access to these operations while navigating through long forms. Please see the examples below for usage demos and for details on how to implement as either a sticky [footer](#bottom) or [header](#top). ### Accessibility For accessibility compliance a ref to the parent container is required to be passed in to the `containerRef` prop. This allows for focus to be observed within the parent container so if an element is focused and obscured by the `FloatingSection` component it can be shifted into view. ## Position Use the `position` prop to set the sticky position. By default the position is set to `bottom`. ### Bottom To use `FloatingSection` as a sticky footer wrap the elements to be included within the component and place it at the bottom of the parent container that holds the desired associated content. While vertically scrolling the component will be visible while the parent container is in view. Once the component has reached the bottom of the screen it will no longer float and with subtle animation will "drop" into its parent container. To maintain a floating state at all times use the [alwaysFloat](#always-float) prop. ```jsx live () => { const StyledForm = styled(FormProvider, { backgroundColor: 'white', }); const form = useForm({ defaultValues: { selectList: '', dateInput: '', dateInputRange: { from: '', to: '' }, radioGroup: null, checkboxGroup: [], textInput1: '', textInput2: '', textInput3: '', textInputArea: '', }, }); const options = [ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]; const [isChecked, setChecked] = useState(false); const onSubmit = (data) => { console.log('data', data); }; const reset = () => { form.reset(); setChecked(false); }; const containerRef = useRef(null); return (
setChecked(e.target.checked)} />
); }; ``` ### Top To use `FloatingSection` as a sticky header set the `position` prop to `top`, wrap the elements to be included within the component and place it at the top of the parent container that holds the desired associated content. While vertically scrolling the component will float once it reaches the top of the screen and remain visible until the parent container is out of view. To maintain a floating state at all times use the [alwaysFloat](#always-float) prop. ```jsx live () => { const StyledForm = styled(FormProvider, { backgroundColor: 'white', }); const form = useForm({ defaultValues: { selectList: '', dateInput: '', dateInputRange: { from: '', to: '' }, radioGroup: null, checkboxGroup: [], textInput1: '', textInput2: '', textInput3: '', textInputArea: '', }, }); const options = [ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]; const onSubmit = (data) => { console.log('data', data); }; const paginationProps = usePagination({ pages: 6 }); const containerRef = useRef(null); return (
Previous Next
); }; ``` ## Always float Use the `alwaysFloat` prop to disable the animation and retain a floating state at all times. ```jsx live () => { const StyledForm = styled(FormProvider, { backgroundColor: 'white', }); const form = useForm({ defaultValues: { selectList: '', dateInput: '', dateInputRange: { from: '', to: '' }, radioGroup: null, checkboxGroup: [], textInput1: '', textInput2: '', textInput3: '', textInputArea: '', }, }); const options = [ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]; const onSubmit = (data) => { console.log('data', data); }; const containerRef = useRef(null); return (
console.log('clicked previous')}> Previous console.log('clicked next')} css={{ marginLeft: 'auto' }} > Next
); }; ``` ## Space Use the `space` prop to adjust the spacing between the `FloatingSection` component and either the top or the bottom of the screen depending on the position setting. The default is `24`. Cannot be `0`. ```jsx live () => { const StyledForm = styled(FormProvider, { backgroundColor: 'white', }); const form = useForm({ defaultValues: { selectList: '', dateInput: '', dateInputRange: { from: '', to: '' }, radioGroup: null, checkboxGroup: [], textInput1: '', textInput2: '', textInput3: '', textInputArea: '', }, }); const options = [ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]; const onSubmit = (data) => { console.log('data', data); }; const containerRef = useRef(null); return (
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed rhoncus id orci sit amet pulvinar. Vivamus at urna pellentesque, commodo enim nec, dictum lorem. Phasellus at facilisis ligula. Pellentesque pharetra ipsum in faucibus convallis. Proin sit amet erat ut libero tempus tristique. Nulla non bibendum orci, et imperdiet elit.
); }; ``` ```jsx render ``` ```jsx render ``` #### Concerns for narrow screens and high magnification - Avoid too much text or wide content layout does not wrap since these can - Cause content to extend outside the FloatingSection - Grow vertically in ways that cover significant portions of a mobile screen #### Avoid using for primary navigation, especially top - When used for navigation, assumptions about FloatingSection "always being available" assumes users can see and click the options in it. - This is most applicable to FloatingSection set to top where keyboard users will have to press Shift-Tab repeatedly to return to the options at the top. --- id: flyout category: Navigation title: Flyout description: Static component with child elements that displays from the right or bottom side of the window and overlays all other content until it is closed. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=44010-121609 sourceIsTS: true --- ```jsx import { Flyout } from '@uhg-abyss/web/ui/Flyout'; ``` ```jsx sandbox { component: 'Flyout', inputs: [ { prop: 'children', type: 'string', }, { prop: 'position', type: 'select', options: [ { label: 'bottom', value: 'bottom' }, { label: 'right', value: 'right' }, ], }, { prop: 'label', type: 'string', }, { prop: 'indent', type: 'string', }, { prop: 'variant', type: 'select', options: [ { label: 'filled', value: 'filled' }, { label: 'outlined', value: 'outlined' }, ], }, ], } () => { return ( Flyout example starts on the right of the screen. See 'Flyout Label'.

This Flyout can be opened with the access key 'F'; the underlined 'F' in the label is to indicate this.
Press Ctrl + Option + F on Mac (Chrome/Safari) or Alt + F on Windows (Chrome).
See the Access Key section below for more details, including a full list of shortcuts.

Here is the Flyout content from the sandbox example.
); } ``` ## Access key The `accessKey` prop sets a keyboard shortcut to open the Flyout from anywhere on the page. This is recommended for accessibility purposes, for users who navigate with the keyboard. By default, `accessKey` is set to the first character of the `label` prop, assuming a label is provided. As a visual indicator, the first character of the label is underlined and bolded to show the access key. To disable this, use the `disableUnderlineAccessKey` prop. If a custom access key is set via the prop, no character is underlined/bolded in the label. To disable the `accessKey` entirely, set the prop to an empty string. The value must consist of a single printable character. This forms part of a keyboard shortcut, which varies depending on the browser and operating system. For Chrome and Safari on Mac, the shortcut is `Ctrl + Option + key`. For Chrome on Windows, the shortcut is `Alt + key`. See the MDN Web Docs for more information, including browser-specific shortcuts. ## Button only The primary function of the Flyout component, as the title suggests, is to expand a small Flyout drawer via a sticky button. Additionally, the Flyout component can be used as a button, to do something like open a modal or a link. This is achieved by passing the `buttonOnly` prop. Use the `onClick` prop to customize the action of the button, such as to open a modal.
To use the button as a link, see the `href` prop. ```jsx live () => { return ( Example with button only, no expanding Flyout drawer. Button has href set with a link to Abyss home. } variant="outlined" indent="40%" buttonOnly showArrowIcon={false} > ); }; ``` ## Variant The `variant` prop offers two color/styling options for the button - `'filled'` and `'outlined'`. `'filled'` is designed for the classic flyout scenario where a small drawer can expand out. `'outlined'` is a secondary style, and is useful for actions such as going to an external feedback form via the `onClick` callback. It can technically be used in the same way as the filled variant, too. For example, if there are 2 different Flyouts on the same page, one can be filled and the other outlined. ## Positioning Use the `position` prop to change where the Flyout is anchored on the screen. Options include `'right'` or `'bottom'` The default position is `'right'`. The `indent` prop offsets the Flyout from its anchored edge. This prop accepts values like pixels ('px') or percentages ('%') to represent the offset distance. The default indent is `'35%'`. - With `position="right"`, increasing the `indent` value moves the Flyout vertically, away from the bottom of the screen. - For `position="bottom"`, increasing the `indent` values moves the Flyout horizontally away from the right side of the screen. `` can be anchored to either the right side or bottom of a screen, as specified by the required `position` prop. Further customization of the `` position can be made with the `indent` prop. If the position is 'bottom', the indent specifies how far up from the bottom of the screen the `` is positioned. If the position is 'right', the indent specifies how far up from the right the `` is positioned. `indent` examples include '30px' or '50%'. ```jsx live () => { return ( Bottom position with a filled variant { console.log('Bottom Flyout open', isExpanded); }} label="Bottom Example" color="$info1" variant="filled" indent="100px" icon={} contentFocus >
You can also customize the color and icon of the Flyout.

); }; ``` ## href The `href` prop allows the Flyout to act as a link. When the Flyout is clicked, the user is redirected to the specified URL. See the [ButtonOnly](#button-only) example for a use case. ## Height and width The height and width props set the size of the Flyout's opened content drawer. The Abyss design team has specified a recommended height and width: - `height` should be between `208px` and `320px` (default: `208px`) - `width` should be between `400px` and `504px` (default: `400px`) When the variant is `'filled'`, and the position is `'right'`, the height of the button is fixed to match the height of the opened menu. Otherwise, the button is sized dynamically. ## Icon An icon can be added to the left side of the Flyout button by passing an [Icon](/web/ui/icon) or [IconSymbol](/web/ui/icon-symbol) component to the icon prop. The left icon is customizable. The right icon is reserved for a chevron icon that can be toggled on or off with the `showArrowIcon` prop - see below. For examples, see [Positioning](#positioning) or [Variant](#variant). ## Show arrow icon The `showArrowIcon` prop displays a chevron icon on the right side of the Flyout button. This is useful for indicating that the button expands a drawer. ## Overflow scrolling When the Flyout is expanded, the Flyout content is scrollable if the content exceeds the height of the Flyout. ```jsx live () => { return ( Example with overflow scrolling and contentFocus prop { console.log('Toggle Overflow Flyout Example'); }} label="Overflow" icon={} variant="outlined" indent="10%" buttonOnly={false} showArrowIcon contentFocus >
- The content scrolls vertically if it overflows.
- In this example, the contentFocus prop is true to allow keyboard focus for accessible navigation.
- Try using the tab button to set focus here and scroll with arrow keys.
{Array.from(Array(10).keys()).map((item) => { return (
---
); })}
); }; ``` ## Content focus The `contentFocus` prop allows the Flyout content container to receive focus when the Flyout is expanded. Then, keyboard users can use the tab key to navigate to the content. This is intended to be used if the contents of the Flyout overflow. Otherwise, it adds an unnecessary tab stop. If there are interactive elements placed within the Flyout content, these will already appear in the tab order, regardless of the contentFocus prop. For example, form controls (``, ``, `<select>`), Links (`<a>`), and Buttons (`<button>`) appear in the tab order by default. ## Responsiveness When the screen hits a breakpoint of 744px or smaller, to ensure visibility of the component, we instead display the expanded form as a [Drawer](/web/ui/drawer). </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={Flyout} rows={[ { name: 'children', type: 'node', description: 'Element displayed when the Flyout is expanded', }, { name: 'color', type: 'string', description: 'Set the color of the Flyout Button', }, { name: 'width', type: 'string | number', description: 'Set the width of the expanded content', }, { name: 'height', type: 'string | number', description: 'Set the height of the expanded content', }, { name: 'variant', type: "'filled' | 'outlined'", description: 'Indicate whether the Flyout is shown with filled primary button or secondary outlined', }, { name: 'position', type: "'right' | 'bottom'", description: 'Indicate whether the Flyout is shown on the bottom or right side of the screen', }, { name: 'icon', type: 'JSX.Element', description: 'The icon to display on the left side of the Flyout button', }, { name: 'onClick', type: 'function', description: 'Used to trigger a custom function when the Flyout is clicked', }, { name: 'indent', type: 'string', description: 'The amount the flyout is shifted from the bottom right corner of the screen', }, { name: 'label', type: 'string', description: 'Title on the Flyout button', }, { name: 'accessKey', type: 'string', description: 'Set the access key to open the Flyout menu with a keyboard shortcut', default: 'First char of label', }, { name: 'contentFocus', type: 'boolean', description: 'If true, the Flyout content container can receive focus when the Flyout is expanded', }, { name: 'href', type: 'string', description: 'URL to redirect to when the Flyout is clicked. Use with buttonOnly', }, { name: 'buttonOnly', type: 'boolean', description: 'If true, the Flyout button does not expand the content drawer', }, { name: 'showArrowIcon', type: 'boolean', description: 'If true, the Flyout button displays an arrow icon', }, { name: 'disableUnderlineAccessKey', type: 'boolean', description: 'If true, the first character is not bolded and underlined to indicate the access key', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Flyout} rows={[ { name: 'flyout-root-container', description: 'Flyout root element', }, { name: 'flyout-content-container', description: 'Flyout content container when expanded', }, { name: 'flyout-responsive-content-drawer-container', description: 'Flyout drawer container when expanded in a small screen size', }, { name: 'flyout-trigger-button', description: 'Flyout button to click to expand or perform other actions', }, { name: 'flyout-button-icon', description: 'Custom icon in the button', }, { name: 'flyout-expand-icon', description: 'Chevron icon in the button', }, { name: 'flyout-button-flex-container', description: 'Flex-box container within the button', }, { name: 'flyout-body-button', description: 'Hidden button at the beginning of the HTML body for accessibility', }, ]} /> ``` </Tab> <Tab label="Accessibility"> The Flyout component is composed of two parts: a "sticky" button positioned on the side of the browser window and modal drawer (dialog) that displayed when activated. When collapsed or displayed, the Flyout button and modal overlay the main content. <h6>Communicating sticky button presence and keyboard access</h6> Since the button is sticky, repositioned to the sides of browser window, and added to the end of the HTML. As result many users, especially those using screen readers, may not realize the button even exists. Keyboard users, if they know the button exists, would have difficulty accessing it in the focus order since is at the end of HTML `<body>`. <h6>Skip links added to top of page</h6> To address both issues, skip links are added to the very top of the page and (ideally) before any "skip to main content" option. Screen reader users are informed of these options at the start of the page. Minor changes for some browsers were made to address in this link to help avoid known conflicts (See BrAT Accesskey Variations below). <h6>Accesskey keyboard shortcut</h6> The skip link also includes the keyboard shortcut to access the Flyout. This uses the standard HTML accesskey which should be familiar to them and their variations (See BrAT Accesskey Variations below). By default, the first letter of Flyout.Label becomes the shortcut key. By default, it is also underlined in the sticky button as a reminder for sighted user. These settings can be overridden (See the Access Key section in the [Overview tab](flyout/?tab=overview#access-key)). <h6>Closing Flyout returns to previous location</h6> Like modal dialogs, closing a Flyout (should) return the focus to whatever element had it when it was opened. Flyout implements this so focus returns to the element that had it when closed. Flyouts can be closed using Escape, pressing Enter on the flyout button, or pressing the flyout accesskey combination again. export const links = { pattern: 'https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/', example: 'https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/dialog/', }; <h6>WAI-ARIA dialog pattern</h6> The closest WAI-ARIA design pattern is the <ExitLink href={links.pattern}> Dialog (Modal) Pattern </ExitLink> and <ExitLink href={links.example}>Modal Dialog Example</ExitLink> . WAI-ARIA currently (WAI-AIRA 1.1 as of 8/1/2024) has no equivalent to the sticky button and its keyboard access. The design and implementation used were created to address the issue covered above. <h6>BrAT Accesskey Variations</h6> - Windows browsers (Chrome, Edge, Firefox) and screen readers (NVDA, JAWS) - Minor accesskey variation: Addition of Shift key Windows accesskey for Chrome and Edge relies on Alt alone. This can cause conflicts accessing some characters Chromium browsers use for their keyboard shortcuts.<br /><br /> Firefox browser implements accesskey requires using Alt + Shift. Using Alt + Shift with the character addresses the issue with letter keys and works the same in all three browsers. This is why the skip links at the top of the page include Shift on Chromium browsers even though they may not be necessary.<br /><br /> Example: On this page, the sandbox example uses accesskey="F" to access the "Flyout Label" example on the right side of this window. Using Edge and Chrome Alt + F opens the File menu. Using Alt + Shift + F accesses Flyout Label as intended.<br /><br /> - MacOS browsers (Safari, Chrome) and screen readers (VoiceOver) - VoiceOver conflict with browser accesskey default - MacOS uses Control + Option and this shown in skip link in Safari and Chrome browsers. - VoiceOver uses Control + Option as its modifier keys creating a conflict when used in the browsers (discussed below) <br /> <br /> - Safari - Keyboard without VoiceOver: Control + Option + Letter (default) - Keyboard with VoiceOver: Control + Letter ONLY - Apple modifies Safari's HTML accesskey implementation to use only Control when VoiceOver is running - Using modified accesskey using Control + [letter] works as described above including resetting focus to originally focused element using Escape, accesskey, and flyout button - Note: Once activated, the Control-only accesskey modification is persistent even if VoiceOver is turned off. Restart Safari without VoiceOver to reset accesskey to Control + Option. <br /> <br /> - Chrome - Keyboard without VoiceOver: Control + Option + Letter (default) - Keyboard with VoiceOver: accesskey "effectively disabled" - Unlike Safari, the HTML accesskey modifier combination remains Control + Option - To use this accesskey combination requires using VoiceOver pass-through mode using Control + Option + Tab - Then use normal Control + Option accesskey combination to open flyout. Operation then works as described resetting focus to originally focused element using Escape, accesskey, and flyout button - Example: To access the Flyout Label example requires pressing Control + Option + Tab, then Control + Option + F <br /> <br /> - For more information about accesskey BrAT implementations see: <ExitLink href="https://pauljadam.com/demos/accesskey.html">Accesskey Accessibility Demo (pauljadam.com)</ExitLink> ```jsx live () => { return ( <React.Fragment> This example demonstrates two flyouts. One on the right. One on the bottom. The one on the right is short. The bottom one has extra, overflowing content. <Flyout label="Flyout Label" indent="60%"> <div style={{ padding: '10px' }}> <Text>Here is the Flyout content from the sandbox example.</Text> </div> </Flyout> <Flyout position="bottom" onClick={(isExpanded) => { console.log('Bottom Flyout open', isExpanded); }} label="Lengthy information" variant="filled" indent="100px" icon={<IconSymbol icon="info" />} contentFocus > <div style={{ padding: '10px' }}> <Text> - The content scrolls vertically if it overflows. <br /> - In this example, the contentFocus prop is true to allow keyboard focus for accessible navigation. <br /> - Try using the tab button to set focus here and scroll with arrow keys. </Text> <br /> {Array.from(Array(10).keys()).map((item) => { return ( <p key={item} style={{ marginBottom: 15, marginTop: 15 }}> Overflow example </p> ); })} </div> </Flyout> <div style={{ height: '20px' }}></div> </React.Fragment> ); }; ``` ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Enter', description: 'Executes the Flyout button trigger to expand or close (when focus is on button)', }, { name: 'Space', description: 'Executes the Flyout button trigger to expand or close (when focus is on button)', }, { name: 'Esc', description: 'Closes the Flyout', }, { name: 'Tab', description: 'Moves focus to Flyout content window when using contentFocus or to focusable element when present in content', }, ]} /> ``` </Tab> --- id: footer-v2 category: Content title: V2Footer description: Used to create a page footer. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=7-2889 sourceIsTS: true subDirectory: Footer --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="PageFooter"></Docs.V2MigrationBanner> ``` ```jsx import { V2Footer } from '@uhg-abyss/web/ui/Footer'; ``` ```jsx live () => { const activeBrand = useAbyssTheme().themeName; const subFooterLinks = [ { label: 'Privacy', href: 'https://www.google.com' }, { label: 'Terms Of Use', href: '#' }, { label: 'Opt Out', href: '#' }, { label: 'Accessibility', href: '#' }, ]; const socialIcons = [ { icon: ( <svg width="11" height="20" viewBox="0 0 11 20" fill="none" xmlns="http://www.w3.org/2000/svg" > <path d="M3 6.66667H0.5V10H3V20H7.16667V10H10.2017L10.5 6.66667H7.16667V5.2775C7.16667 4.48167 7.32667 4.16667 8.09583 4.16667H10.5V0H7.32667C4.33 0 3 1.31917 3 3.84583V6.66667Z" /> </svg> ), href: '#', title: 'Facebook', }, { icon: ( <svg width="19" height="18" viewBox="0 0 19 18" fill="none" xmlns="http://www.w3.org/2000/svg" > <path d="M9.5 1.62225C11.903 1.62225 12.188 1.63125 13.1375 1.67475C15.5765 1.78575 16.7157 2.943 16.8267 5.364C16.8703 6.31275 16.8785 6.59775 16.8785 9.00075C16.8785 11.4045 16.8695 11.6887 16.8267 12.6375C16.715 15.0562 15.5787 16.2157 13.1375 16.3267C12.188 16.3703 11.9045 16.3792 9.5 16.3792C7.097 16.3792 6.812 16.3703 5.86325 16.3267C3.41825 16.215 2.285 15.0525 2.174 12.6368C2.1305 11.688 2.1215 11.4037 2.1215 9C2.1215 6.597 2.13125 6.31275 2.174 5.36325C2.28575 2.943 3.422 1.785 5.86325 1.674C6.81275 1.63125 7.097 1.62225 9.5 1.62225ZM9.5 0C7.05575 0 6.74975 0.0105 5.78975 0.054C2.52125 0.204 0.70475 2.0175 0.55475 5.289C0.5105 6.24975 0.5 6.55575 0.5 9C0.5 11.4443 0.5105 11.751 0.554 12.711C0.704 15.9795 2.5175 17.796 5.789 17.946C6.74975 17.9895 7.05575 18 9.5 18C11.9443 18 12.251 17.9895 13.211 17.946C16.4765 17.796 18.2975 15.9825 18.4452 12.711C18.4895 11.751 18.5 11.4443 18.5 9C18.5 6.55575 18.4895 6.24975 18.446 5.28975C18.299 2.02425 16.4832 0.20475 13.2118 0.05475C12.251 0.0105 11.9443 0 9.5 0ZM9.5 4.3785C6.94775 4.3785 4.8785 6.44775 4.8785 9C4.8785 11.5522 6.94775 13.6222 9.5 13.6222C12.0522 13.6222 14.1215 11.553 14.1215 9C14.1215 6.44775 12.0522 4.3785 9.5 4.3785ZM9.5 12C7.84325 12 6.5 10.6575 6.5 9C6.5 7.34325 7.84325 6 9.5 6C11.1567 6 12.5 7.34325 12.5 9C12.5 10.6575 11.1567 12 9.5 12ZM14.3045 3.11625C13.7075 3.11625 13.2238 3.6 13.2238 4.19625C13.2238 4.7925 13.7075 5.27625 14.3045 5.27625C14.9007 5.27625 15.3837 4.7925 15.3837 4.19625C15.3837 3.6 14.9007 3.11625 14.3045 3.11625Z" /> </svg> ), href: '#', title: 'Instagram', }, { icon: ( <svg width="17" height="16" viewBox="0 0 17 16" fill="none" xmlns="http://www.w3.org/2000/svg" > <path d="M3.5275 1.73913C3.5275 2.69983 2.74125 3.47826 1.77083 3.47826C0.800417 3.47826 0.0141667 2.69983 0.0141667 1.73913C0.0141667 0.77913 0.800417 0 1.77083 0C2.74125 0 3.5275 0.77913 3.5275 1.73913ZM3.54167 4.86957H0V16H3.54167V4.86957ZM9.19558 4.86957H5.67658V16H9.19629V10.1572C9.19629 6.90852 13.4668 6.64278 13.4668 10.1572V16H17V8.95235C17 3.47061 10.6803 3.67026 9.19558 6.3687V4.86957Z" /> </svg> ), href: '#', title: 'LinkedIn', }, ]; return ( <V2Footer> <V2Footer.MainContent> <V2Footer.Brandmark> <Brandmark affiliate={activeBrand} size="$sm" variant="lockup" color="white" brand={activeBrand} /> </V2Footer.Brandmark> <V2Footer.Sections> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> </V2Footer.Sections> <V2Footer.Social title="Follow us" icons={socialIcons} securityImage={ <img src="/img/graphics/footer/v2footer_security_image.png" alt="Secured by Sectigo" /> } /> </V2Footer.MainContent> <V2Footer.SubFooter copyright={ activeBrand === 'optum' ? 'Optum, Inc. All rights reserved.' : 'United HealthCare Services, Inc. All rights reserved.' } links={subFooterLinks} brandmark={ <Brandmark brand={activeBrand} size="$sm" affiliate={activeBrand} variant="lockup" color="white" /> } /> </V2Footer> ); }; ``` ## Variants The default `variant` of `V2Footer` has a dark blue background and white text. Use `'alt'` for a light color scheme with dark text. ```jsx live () => { const activeBrand = useAbyssTheme().themeName; const subFooterLinks = [ { label: 'Privacy', href: 'https://www.google.com' }, { label: 'Terms Of Use', href: '#' }, { label: 'Opt Out', href: '#' }, { label: 'Accessibility', href: '#' }, ]; return ( <V2Footer variant="alt"> <V2Footer.MainContent> <V2Footer.Brandmark> <Brandmark affiliate={activeBrand} size="$sm" variant="lockup" color={activeBrand === 'optum' ? 'orange' : 'blue'} brand={activeBrand} /> </V2Footer.Brandmark> <V2Footer.Sections> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> </V2Footer.Sections> </V2Footer.MainContent> <V2Footer.SubFooter copyright={ activeBrand === 'optum' ? 'Optum, Inc. All rights reserved.' : 'United HealthCare Services, Inc. All rights reserved.' } links={subFooterLinks} brandmark={ <Brandmark brand={activeBrand} size="$sm" affiliate={activeBrand} variant="lockup" color={activeBrand === 'optum' ? 'orange' : 'blue'} /> } /> </V2Footer> ); }; ``` ## V2Footer.Upper For additional customization, use `Footer.Upper` as a slot that goes above the main footer. ```jsx live () => { const activeBrand = useAbyssTheme().themeName; return ( <V2Footer> <V2Footer.Upper> <Layout.Group alignLayout="between" alignItems="top"> <Heading offset={3} color="white"> Footer </Heading> <V2Button variant="outline" size="$sm" href="#" icon={{ icon: 'keyboard_arrow_up', position: 'trailing' }} > Go to top </V2Button> </Layout.Group> </V2Footer.Upper> <V2Footer.MainContent> <V2Footer.Sections> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> </V2Footer.Sections> </V2Footer.MainContent> <V2Footer.SubFooter copyright={ activeBrand === 'optum' ? 'Optum, Inc. All rights reserved.' : 'United HealthCare Services, Inc. All rights reserved.' } /> </V2Footer> ); }; ``` ## V2Footer.MainContent The main content of the footer is wrapped in `Footer.MainContent`. ## V2Footer.Brandmark There are two optional locations to add a logo to the footer. Subcomponent `V2Footer.Brandmark` is the upper left location, while the prop `brandmark` on `V2Footer.SubFooter` is in the bottom right. ```jsx live () => { const activeBrand = useAbyssTheme().themeName; const subFooterLinks = [ { label: 'Privacy', href: 'https://www.google.com' }, { label: 'Terms Of Use', href: '#' }, { label: 'Opt Out', href: '#' }, { label: 'Accessibility', href: '#' }, ]; return ( <V2Footer> <V2Footer.MainContent> <V2Footer.Brandmark> <Brandmark affiliate={activeBrand} size="$sm" variant="lockup" color="white" brand={activeBrand} /> </V2Footer.Brandmark> <V2Footer.Sections> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> </V2Footer.Sections> </V2Footer.MainContent> <V2Footer.SubFooter copyright={ activeBrand === 'optum' ? 'Optum, Inc. All rights reserved.' : 'United HealthCare Services, Inc. All rights reserved.' } links={subFooterLinks} brandmark={ <Brandmark brand={activeBrand} size="$sm" affiliate={activeBrand} variant="lockup" color="white" /> } /> </V2Footer> ); }; ``` ## Social `V2Footer.Social` adds a section on the right of the footer dedicated to social media links. There are two ways to utilize this section: the predefined layout or a custom layout. ### Predefined layout The predefined layout is a basic layout with space for icon links and an optional site security image. To use this option, provide the following props to `V2Footer.Social`: ```ts { title?: string; headingLevel?: 1 | 2 | 3 | 4 | 5 | 6; icons?: Array<{ icon: string | { icon: string; variant: 'filled' | 'outlined' } | React.ReactElement; href: string; title: string; }>; securityImage?: string; } ``` - `title`: The title of the social media section. - `headingLevel`: The heading level to use for the title. Default is `2`. - `icons`: An array of objects with the following properties: - `icon`: The icon to display. Use a string of an object with the `icon` and `variant` values to use an [IconSymbol](/web/ui/icon-symbol). Use a `ReactElement` to provide a custom icon. - `href`: The URL the icon links to. - `title`: The accessible title of the icon link. - `securityImage`: An optional image to display at the bottom of the social media section. ```jsx live () => { const activeBrand = useAbyssTheme().themeName; const subFooterLinks = [ { label: 'Privacy', href: 'https://www.google.com' }, { label: 'Terms Of Use', href: '#' }, { label: 'Opt Out', href: '#' }, { label: 'Accessibility', href: '#' }, ]; const socialIcons = [ { icon: ( <svg width="11" height="20" viewBox="0 0 11 20" fill="none" xmlns="http://www.w3.org/2000/svg" > <path d="M3 6.66667H0.5V10H3V20H7.16667V10H10.2017L10.5 6.66667H7.16667V5.2775C7.16667 4.48167 7.32667 4.16667 8.09583 4.16667H10.5V0H7.32667C4.33 0 3 1.31917 3 3.84583V6.66667Z" /> </svg> ), href: '#', title: 'Facebook', }, { icon: ( <svg width="19" height="18" viewBox="0 0 19 18" fill="none" xmlns="http://www.w3.org/2000/svg" > <path d="M9.5 1.62225C11.903 1.62225 12.188 1.63125 13.1375 1.67475C15.5765 1.78575 16.7157 2.943 16.8267 5.364C16.8703 6.31275 16.8785 6.59775 16.8785 9.00075C16.8785 11.4045 16.8695 11.6887 16.8267 12.6375C16.715 15.0562 15.5787 16.2157 13.1375 16.3267C12.188 16.3703 11.9045 16.3792 9.5 16.3792C7.097 16.3792 6.812 16.3703 5.86325 16.3267C3.41825 16.215 2.285 15.0525 2.174 12.6368C2.1305 11.688 2.1215 11.4037 2.1215 9C2.1215 6.597 2.13125 6.31275 2.174 5.36325C2.28575 2.943 3.422 1.785 5.86325 1.674C6.81275 1.63125 7.097 1.62225 9.5 1.62225ZM9.5 0C7.05575 0 6.74975 0.0105 5.78975 0.054C2.52125 0.204 0.70475 2.0175 0.55475 5.289C0.5105 6.24975 0.5 6.55575 0.5 9C0.5 11.4443 0.5105 11.751 0.554 12.711C0.704 15.9795 2.5175 17.796 5.789 17.946C6.74975 17.9895 7.05575 18 9.5 18C11.9443 18 12.251 17.9895 13.211 17.946C16.4765 17.796 18.2975 15.9825 18.4452 12.711C18.4895 11.751 18.5 11.4443 18.5 9C18.5 6.55575 18.4895 6.24975 18.446 5.28975C18.299 2.02425 16.4832 0.20475 13.2118 0.05475C12.251 0.0105 11.9443 0 9.5 0ZM9.5 4.3785C6.94775 4.3785 4.8785 6.44775 4.8785 9C4.8785 11.5522 6.94775 13.6222 9.5 13.6222C12.0522 13.6222 14.1215 11.553 14.1215 9C14.1215 6.44775 12.0522 4.3785 9.5 4.3785ZM9.5 12C7.84325 12 6.5 10.6575 6.5 9C6.5 7.34325 7.84325 6 9.5 6C11.1567 6 12.5 7.34325 12.5 9C12.5 10.6575 11.1567 12 9.5 12ZM14.3045 3.11625C13.7075 3.11625 13.2238 3.6 13.2238 4.19625C13.2238 4.7925 13.7075 5.27625 14.3045 5.27625C14.9007 5.27625 15.3837 4.7925 15.3837 4.19625C15.3837 3.6 14.9007 3.11625 14.3045 3.11625Z" /> </svg> ), href: '#', title: 'Instagram', }, { icon: ( <svg width="17" height="16" viewBox="0 0 17 16" fill="none" xmlns="http://www.w3.org/2000/svg" > <path d="M3.5275 1.73913C3.5275 2.69983 2.74125 3.47826 1.77083 3.47826C0.800417 3.47826 0.0141667 2.69983 0.0141667 1.73913C0.0141667 0.77913 0.800417 0 1.77083 0C2.74125 0 3.5275 0.77913 3.5275 1.73913ZM3.54167 4.86957H0V16H3.54167V4.86957ZM9.19558 4.86957H5.67658V16H9.19629V10.1572C9.19629 6.90852 13.4668 6.64278 13.4668 10.1572V16H17V8.95235C17 3.47061 10.6803 3.67026 9.19558 6.3687V4.86957Z" /> </svg> ), href: '#', title: 'LinkedIn', }, { icon: ( <svg width="21" height="16" viewBox="0 0 21 16" fill="none" xmlns="http://www.w3.org/2000/svg" > <path d="M16.8458 0.653316C13.8425 0.448316 7.15333 0.449149 4.15417 0.653316C0.906667 0.874982 0.524167 2.83665 0.5 7.99998C0.524167 13.1541 0.903333 15.1241 4.15417 15.3466C7.15417 15.5508 13.8425 15.5516 16.8458 15.3466C20.0933 15.125 20.4758 13.1633 20.5 7.99998C20.4758 2.84582 20.0967 0.875816 16.8458 0.653316ZM8 11.3333V4.66665L14.6667 7.99415L8 11.3333Z" /> </svg> ), href: '#', title: 'Youtube', }, ]; return ( <V2Footer> <V2Footer.MainContent> <V2Footer.Sections> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> </V2Footer.Sections> <V2Footer.Social title="Follow us" icons={socialIcons} securityImage={ <img src="/img/graphics/footer/v2footer_security_image.png" alt="Secured by Sectigo" /> } /> </V2Footer.MainContent> <V2Footer.SubFooter copyright={ activeBrand === 'optum' ? 'Optum, Inc. All rights reserved.' : 'United HealthCare Services, Inc. All rights reserved.' } links={subFooterLinks} brandmark={ <Brandmark brand={activeBrand} size="$sm" affiliate={activeBrand} variant="lockup" color="white" /> } /> </V2Footer> ); }; ``` ### Custom layout `V2Footer.Social` also accepts a `ReactNode` for custom layouts. Below is an example with a custom section: ```jsx live () => { const activeBrand = useAbyssTheme().themeName; const subFooterLinks = [ { label: 'Privacy', href: 'https://www.google.com' }, { label: 'Terms Of Use', href: '#' }, { label: 'Opt Out', href: '#' }, { label: 'Accessibility', href: '#' }, ]; return ( <V2Footer> <V2Footer.MainContent> <V2Footer.Sections> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> </V2Footer.Sections> <V2Footer.Social> <Layout.Stack alignItems="left"> <V2Footer.Section title="Social Media" /> <Layout.Group> <V2Link href="#" variant="alt" css={{ 'abyss-link-root': { lineHeight: '0 !important' } }} > <Icon size="$footer-v2-sections.sizing.all.icon" color="white" title="Facebook" > <svg width="11" height="20" viewBox="0 0 11 20" fill="none" xmlns="http://www.w3.org/2000/svg" > <path d="M3 6.66667H0.5V10H3V20H7.16667V10H10.2017L10.5 6.66667H7.16667V5.2775C7.16667 4.48167 7.32667 4.16667 8.09583 4.16667H10.5V0H7.32667C4.33 0 3 1.31917 3 3.84583V6.66667Z" /> </svg> </Icon> </V2Link> <V2Link href="#" variant="alt" css={{ 'abyss-link-root': { lineHeight: '0 !important' } }} > <Icon size="$footer-v2-sections.sizing.all.icon" color="white" title="LinkedIn" > <svg width="17" height="16" viewBox="0 0 17 16" fill="none" xmlns="http://www.w3.org/2000/svg" > <path d="M3.5275 1.73913C3.5275 2.69983 2.74125 3.47826 1.77083 3.47826C0.800417 3.47826 0.0141667 2.69983 0.0141667 1.73913C0.0141667 0.77913 0.800417 0 1.77083 0C2.74125 0 3.5275 0.77913 3.5275 1.73913ZM3.54167 4.86957H0V16H3.54167V4.86957ZM9.19558 4.86957H5.67658V16H9.19629V10.1572C9.19629 6.90852 13.4668 6.64278 13.4668 10.1572V16H17V8.95235C17 3.47061 10.6803 3.67026 9.19558 6.3687V4.86957Z" /> </svg> </Icon> </V2Link> <V2Link href="#" variant="alt" css={{ 'abyss-link-root': { lineHeight: '0 !important' } }} > <Icon size="$footer-v2-sections.sizing.all.icon" color="white" title="Instagram" > <svg width="19" height="18" viewBox="0 0 19 18" fill="none" xmlns="http://www.w3.org/2000/svg" > <path d="M9.5 1.62225C11.903 1.62225 12.188 1.63125 13.1375 1.67475C15.5765 1.78575 16.7157 2.943 16.8267 5.364C16.8703 6.31275 16.8785 6.59775 16.8785 9.00075C16.8785 11.4045 16.8695 11.6887 16.8267 12.6375C16.715 15.0562 15.5787 16.2157 13.1375 16.3267C12.188 16.3703 11.9045 16.3792 9.5 16.3792C7.097 16.3792 6.812 16.3703 5.86325 16.3267C3.41825 16.215 2.285 15.0525 2.174 12.6368C2.1305 11.688 2.1215 11.4037 2.1215 9C2.1215 6.597 2.13125 6.31275 2.174 5.36325C2.28575 2.943 3.422 1.785 5.86325 1.674C6.81275 1.63125 7.097 1.62225 9.5 1.62225ZM9.5 0C7.05575 0 6.74975 0.0105 5.78975 0.054C2.52125 0.204 0.70475 2.0175 0.55475 5.289C0.5105 6.24975 0.5 6.55575 0.5 9C0.5 11.4443 0.5105 11.751 0.554 12.711C0.704 15.9795 2.5175 17.796 5.789 17.946C6.74975 17.9895 7.05575 18 9.5 18C11.9443 18 12.251 17.9895 13.211 17.946C16.4765 17.796 18.2975 15.9825 18.4452 12.711C18.4895 11.751 18.5 11.4443 18.5 9C18.5 6.55575 18.4895 6.24975 18.446 5.28975C18.299 2.02425 16.4832 0.20475 13.2118 0.05475C12.251 0.0105 11.9443 0 9.5 0ZM9.5 4.3785C6.94775 4.3785 4.8785 6.44775 4.8785 9C4.8785 11.5522 6.94775 13.6222 9.5 13.6222C12.0522 13.6222 14.1215 11.553 14.1215 9C14.1215 6.44775 12.0522 4.3785 9.5 4.3785ZM9.5 12C7.84325 12 6.5 10.6575 6.5 9C6.5 7.34325 7.84325 6 9.5 6C11.1567 6 12.5 7.34325 12.5 9C12.5 10.6575 11.1567 12 9.5 12ZM14.3045 3.11625C13.7075 3.11625 13.2238 3.6 13.2238 4.19625C13.2238 4.7925 13.7075 5.27625 14.3045 5.27625C14.9007 5.27625 15.3837 4.7925 15.3837 4.19625C15.3837 3.6 14.9007 3.11625 14.3045 3.11625Z" /> </svg> </Icon> </V2Link> </Layout.Group> <img src="/img/graphics/footer/v2footer_security_image.png" alt="Secured by Sectigo" /> </Layout.Stack> </V2Footer.Social> </V2Footer.MainContent> <V2Footer.SubFooter copyright={ activeBrand === 'optum' ? 'Optum, Inc. All rights reserved.' : 'United HealthCare Services, Inc. All rights reserved.' } links={subFooterLinks} brandmark={ <Brandmark brand={activeBrand} size="$sm" affiliate={activeBrand} variant="lockup" color="white" /> } /> </V2Footer> ); }; ``` ## V2Footer.Sections `V2Footer.Sections` is a container for `V2Footer.Section` components. It allows for the prop `spreadSections` to be passed down to control the alignment of the sections. Default is set to `true`. When `false`, content is left-aligned. ```jsx live () => { const activeBrand = useAbyssTheme().themeName; const subFooterLinks = [ { label: 'Privacy', href: '#' }, { label: 'Terms Of Use', href: '#' }, { label: 'Opt Out', href: '#' }, { label: 'Accessibility', href: '#' }, ]; return ( <V2Footer> <V2Footer.MainContent> <V2Footer.Sections spreadSections={false}> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> <V2Footer.Section title="Section Title"> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> </V2Footer.Section> </V2Footer.Sections> </V2Footer.MainContent> <V2Footer.SubFooter copyright={ activeBrand === 'optum' ? 'Optum, Inc. All rights reserved.' : 'United HealthCare Services, Inc. All rights reserved.' } links={subFooterLinks} /> </V2Footer> ); }; ``` ## V2Footer.Section Each individual section is wrapped in `V2Footer.Section`. Use the `title` prop to add a title to the footer section container. For accessibility purposes, section titles are implemented as HTML headers—`<h2>` elements by default. Use the `headingLevel` prop to change the heading level. ```jsx live <V2Footer> <V2Footer.MainContent> <V2Footer.Sections> <V2Footer.Section title="h2 Section Title" /> <V2Footer.Section title="h3 Section Title" headingLevel={3}> <V2Footer.Link href="#">With a link</V2Footer.Link> <V2Footer.Link href="#">With another link</V2Footer.Link> </V2Footer.Section> <V2Footer.Section> <V2Footer.Link href="#">This section has no title</V2Footer.Link> <V2Footer.Link href="#">But there can still be links</V2Footer.Link> <V2Footer.Link href="#">Like this one</V2Footer.Link> </V2Footer.Section> </V2Footer.Sections> </V2Footer.MainContent> <V2Footer.SubFooter /> </V2Footer> ``` ## V2Footer.Link The `V2Footer.Link` sub-component leverages props from the `V2Link` component. Find additional resources on our [V2Link page](/web/ui/link-v2). Use the `href` prop to set the URL of the link. ```jsx live <V2Footer> <V2Footer.MainContent> <V2Footer.Section title="Section Title"> <V2Footer.Link href="https://www.google.com">Regular Link</V2Footer.Link> <V2Footer.Link href="#">Based On Root Path</V2Footer.Link> </V2Footer.Section> </V2Footer.MainContent> </V2Footer> ``` Use the `onClick` prop to trigger a custom function when the footer link title is clicked. ```jsx live <V2Footer> <V2Footer.MainContent> <V2Footer.Section title="Section Title"> <V2Footer.Link onClick={() => { console.log('onClick triggered'); }} > Page Link onClick </V2Footer.Link> </V2Footer.Section> </V2Footer.MainContent> <V2Footer.SubFooter /> </V2Footer> ``` Use the `openNewWindow` prop to specify whether links open in a new window. `openNewWindow` is false for relative links. Absolute links will open in a new window. ```jsx live <V2Footer spreadSections={false}> <V2Footer.MainContent> <V2Footer.Sections> <V2Footer.Section title="Relative Link"> <V2Footer.Link href="#">Relative - Same Window</V2Footer.Link> <V2Footer.Link href="#" openNewWindow> Relative - New Window </V2Footer.Link> </V2Footer.Section> <V2Footer.Section title="Absolute Link"> <V2Footer.Link href="https://www.google.com" openNewWindow={false}> Absolute - Same Window </V2Footer.Link> <V2Footer.Link href="https://www.google.com"> Absolute - New Window </V2Footer.Link> </V2Footer.Section> </V2Footer.Sections> </V2Footer.MainContent> </V2Footer> ``` ## V2Footer.SubFooter To customize the sub-footer, use the `V2Footer.SubFooter` sub-component. This sub-component accepts children of type `React.ReactNode`, similar to `V2Footer.Upper`, or the following props: ```ts { copyright?: string; links?: Array<{ label: string, href: string }>; bottomText?: string | React.ReactNode; brandmark?: React.ReactNode; name?: string; } ``` - `copyright`: The text to display in the copyright section. - `links`: An array of objects with the following properties: - `label`: The text of the link. - `href`: The URL the link points to. - `bottomText`: Text to display below the copyright. - `brandmark`: A logo to display in the sub-footer. - `name`: The name of the sub-footer for accessibility purposes. ### Sub-footer copyright Use the `copyright` prop to change the title of the copyright section. ```jsx live () => { const activeBrand = useAbyssTheme().themeName; return ( <V2Footer> <V2Footer.SubFooter copyright={ activeBrand === 'optum' ? 'Optum, Inc. All rights reserved.' : 'United HealthCare Services, Inc. All rights reserved.' } /> </V2Footer> ); }; ``` ### Sub-footer bottom text Use the `bottomText` prop to add content below the copyright text. ```jsx live () => { const activeBrand = useAbyssTheme().themeName; return ( <V2Footer> <V2Footer.SubFooter copyright={ activeBrand === 'optum' ? 'Optum, Inc. All rights reserved.' : 'United HealthCare Services, Inc. All rights reserved.' } bottomText="Last updated: 03/15/2023 at 12:01 AM CT" /> </V2Footer> ); }; ``` ### Sub-footer links Use the `links` prop to add the sub-footer link array. Use `href` to set the link to a different page, and use `label` to set the descriptive text for the `href`. ```jsx live () => { const subFooterLinks = [ { label: 'Privacy', href: 'https://www.google.com' }, { label: 'Terms Of Use', href: '#' }, { label: 'Opt Out', href: '#' }, { label: 'Accessibility', href: '#' }, ]; return ( <V2Footer> <V2Footer.SubFooter links={subFooterLinks} /> </V2Footer> ); }; ``` ## Footer name and sub-footer name `V2Footer.Sections`s prop `footerName` and `V2Footer.SubFooter`s `name` are used for accessibility purposes. If you have more than one footer on a page, `footerName` and `name` can help differentiate them for screen readers. ```jsx live <Layout.Stack grow> <V2Footer> <V2Footer.Sections footerName="footer 1 section"> <V2Footer.Section title="footer 1 individual section " /> </V2Footer.Sections> <V2Footer.SubFooter bottomText="First footer" name="sub-footer 1" /> </V2Footer> <V2Footer> <V2Footer.Sections footerName="footer 2 section"> <V2Footer.Section title="footer 2 individual section" /> </V2Footer.Sections> <V2Footer.SubFooter bottomText="Second footer" name="sub-footer 2" /> </V2Footer> </Layout.Stack> ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2Footer" propTypeName="FooterProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="V2Footer.Upper" propTypeName="FooterUpperProps" /> ``` ```jsx render <Docs.V2WebPropsTable title="V2Footer.MainContent" propTypeName="FooterMainContentProps" /> ``` ```jsx render <Docs.V2WebPropsTable title="V2Footer.Brandmark" propTypeName="FooterBrandmarkProps" /> ``` ```jsx render <Docs.V2WebPropsTable title="V2Footer.Sections" propTypeName="FooterSectionsProps" /> ``` ```jsx render <Docs.V2WebPropsTable title="V2Footer.Section" propTypeName="FooterSectionProps" /> ``` ```jsx render <Docs.V2WebPropsTable title="V2Footer.Link" propTypeName="FooterLinkProps" /> ``` ```jsx render <Docs.V2WebPropsTable title="V2Footer.Social" propTypeName="FooterSocialProps" /> ``` ```jsx render <Docs.V2WebPropsTable title="V2Footer.SubFooter" propTypeName="FooterSubFooterProps" /> ``` ```jsx render <Docs.V2ClassesTable title="V2Footer" classes={[FooterClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2Footer.Upper" classes={[FooterUpperClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2Footer.MainContent" classes={[FooterMainContentClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2Footer.Brandmark" classes={[FooterBrandmarkClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2Footer.Sections" classes={[FooterSectionsClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2Footer.Section" classes={[FooterSectionClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2Footer.Link" classes={[FooterLinkClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2Footer.Social" classes={[FooterSocialClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2Footer.SubFooter" classes={[FooterSubFooterClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Tab', description: 'Moves focus to the next focusable element; all focusable elements in the footer are included in the page Tab sequence.', }, { name: 'Shift + Tab', description: 'Moves focus to the previous focusable element; all focusable elements in the footer are included in the page Tab sequence.', }, { name: 'Enter', description: 'When focus is on the link element, pressing Enter will take the user to a separate page.', }, ]} /> ``` ```jsx live () => { const subFooterLinks = [ { label: 'Contact us', href: '#' }, { label: 'Careers', href: '#' }, { label: 'About us', href: '#' }, { label: 'Accessibility', href: '#' }, { label: 'Privacy', href: '#' }, { label: 'Terms Of Use', href: '#' }, { label: 'Legal', href: '#' }, ]; const socialIcons = [ { icon: ( <svg width="11" height="20" viewBox="0 0 11 20" fill="none" xmlns="http://www.w3.org/2000/svg" > <path d="M3 6.66667H0.5V10H3V20H7.16667V10H10.2017L10.5 6.66667H7.16667V5.2775C7.16667 4.48167 7.32667 4.16667 8.09583 4.16667H10.5V0H7.32667C4.33 0 3 1.31917 3 3.84583V6.66667Z" /> </svg> ), href: '#', title: 'Facebook', }, { icon: ( <svg width="19" height="18" viewBox="0 0 19 18" fill="none" xmlns="http://www.w3.org/2000/svg" > <path d="M9.5 1.62225C11.903 1.62225 12.188 1.63125 13.1375 1.67475C15.5765 1.78575 16.7157 2.943 16.8267 5.364C16.8703 6.31275 16.8785 6.59775 16.8785 9.00075C16.8785 11.4045 16.8695 11.6887 16.8267 12.6375C16.715 15.0562 15.5787 16.2157 13.1375 16.3267C12.188 16.3703 11.9045 16.3792 9.5 16.3792C7.097 16.3792 6.812 16.3703 5.86325 16.3267C3.41825 16.215 2.285 15.0525 2.174 12.6368C2.1305 11.688 2.1215 11.4037 2.1215 9C2.1215 6.597 2.13125 6.31275 2.174 5.36325C2.28575 2.943 3.422 1.785 5.86325 1.674C6.81275 1.63125 7.097 1.62225 9.5 1.62225ZM9.5 0C7.05575 0 6.74975 0.0105 5.78975 0.054C2.52125 0.204 0.70475 2.0175 0.55475 5.289C0.5105 6.24975 0.5 6.55575 0.5 9C0.5 11.4443 0.5105 11.751 0.554 12.711C0.704 15.9795 2.5175 17.796 5.789 17.946C6.74975 17.9895 7.05575 18 9.5 18C11.9443 18 12.251 17.9895 13.211 17.946C16.4765 17.796 18.2975 15.9825 18.4452 12.711C18.4895 11.751 18.5 11.4443 18.5 9C18.5 6.55575 18.4895 6.24975 18.446 5.28975C18.299 2.02425 16.4832 0.20475 13.2118 0.05475C12.251 0.0105 11.9443 0 9.5 0ZM9.5 4.3785C6.94775 4.3785 4.8785 6.44775 4.8785 9C4.8785 11.5522 6.94775 13.6222 9.5 13.6222C12.0522 13.6222 14.1215 11.553 14.1215 9C14.1215 6.44775 12.0522 4.3785 9.5 4.3785ZM9.5 12C7.84325 12 6.5 10.6575 6.5 9C6.5 7.34325 7.84325 6 9.5 6C11.1567 6 12.5 7.34325 12.5 9C12.5 10.6575 11.1567 12 9.5 12ZM14.3045 3.11625C13.7075 3.11625 13.2238 3.6 13.2238 4.19625C13.2238 4.7925 13.7075 5.27625 14.3045 5.27625C14.9007 5.27625 15.3837 4.7925 15.3837 4.19625C15.3837 3.6 14.9007 3.11625 14.3045 3.11625Z" /> </svg> ), href: '#', title: 'Instagram', }, { icon: ( <svg width="17" height="16" viewBox="0 0 17 16" fill="none" xmlns="http://www.w3.org/2000/svg" > <path d="M3.5275 1.73913C3.5275 2.69983 2.74125 3.47826 1.77083 3.47826C0.800417 3.47826 0.0141667 2.69983 0.0141667 1.73913C0.0141667 0.77913 0.800417 0 1.77083 0C2.74125 0 3.5275 0.77913 3.5275 1.73913ZM3.54167 4.86957H0V16H3.54167V4.86957ZM9.19558 4.86957H5.67658V16H9.19629V10.1572C9.19629 6.90852 13.4668 6.64278 13.4668 10.1572V16H17V8.95235C17 3.47061 10.6803 3.67026 9.19558 6.3687V4.86957Z" /> </svg> ), href: '#', title: 'LinkedIn', }, { icon: ( <svg width="21" height="16" viewBox="0 0 21 16" fill="none" xmlns="http://www.w3.org/2000/svg" > <path d="M16.8458 0.653316C13.8425 0.448316 7.15333 0.449149 4.15417 0.653316C0.906667 0.874982 0.524167 2.83665 0.5 7.99998C0.524167 13.1541 0.903333 15.1241 4.15417 15.3466C7.15417 15.5508 13.8425 15.5516 16.8458 15.3466C20.0933 15.125 20.4758 13.1633 20.5 7.99998C20.4758 2.84582 20.0967 0.875816 16.8458 0.653316ZM8 11.3333V4.66665L14.6667 7.99415L8 11.3333Z" /> </svg> ), href: '#', title: 'Youtube', }, ]; return ( <V2Footer> <V2Footer.MainContent> <V2Footer.Brandmark> <Brandmark brand="uhc" affiliate="uhc" size="$md" variant="stacked_wordmark" color="white" /> </V2Footer.Brandmark> <V2Footer.Sections spreadSections={false} footerName="Primary"> <V2Footer.Section title="UHC Health Matters"> <V2Footer.Link href="#">Newsroom</V2Footer.Link> <V2Footer.Link href="#">Community</V2Footer.Link> <V2Footer.Link href="#">Medicare articles</V2Footer.Link> <V2Footer.Link href="#">All news & articles</V2Footer.Link> </V2Footer.Section> <V2Footer.Section title="Health & wellness"> <V2Footer.Link href="#">Vaccines</V2Footer.Link> <V2Footer.Link href="#">Flu short</V2Footer.Link> <V2Footer.Link href="#">Page Link</V2Footer.Link> <V2Footer.Link href="#">All health & wellness topics</V2Footer.Link> </V2Footer.Section> <V2Footer.Section title="More UHC sites"> <V2Footer.Link href="#">Employers</V2Footer.Link> <V2Footer.Link href="#">Agents & brokers</V2Footer.Link> <V2Footer.Link href="#">Providers</V2Footer.Link> </V2Footer.Section> </V2Footer.Sections> <V2Footer.Social title="Follow Us" icons={socialIcons} securityImage={ <img src="/img/graphics/footer/v2footer_security_image.png" alt="Secured by Sectigo" /> } /> </V2Footer.MainContent> <V2Footer.SubFooter copyright="United HealthCare Services, Inc. All rights reserved." bottomText="Last updated: 09/23/2024 at 8:00 PM CT" links={subFooterLinks} brandmark={ <Brandmark brand="uhc" size="40" affiliate="uhc" variant="monogram" color="white" /> } name="Site info" /> </V2Footer> ); }; ``` </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={'Footer'} keys={['footerV2']} /> ``` ```jsx render <Docs.ComponentTokensTable of={'Footnote'} keys={['footerV2Footnote']} /> ``` ```jsx render <Docs.ComponentTokensTable of={'Link'} keys={['footerV2Link']} /> ``` ```jsx render <Docs.ComponentTokensTable of={'Sections'} keys={['footerV2Sections']} /> ``` </Tab> --- id: form-builder category: Forms title: FormBuilder (Beta) description: Used for creating and rendering forms. pagination_prev: web/ui/file-upload pagination_next: web/ui/number-input isHidden: true --- <Tab label="Overview"> ```jsx import { FormBuilder } from '@uhg-abyss/web/ui/FormBuilder'; ``` ```jsx render <Docs.V2Deprecated componentName="FormBuilder"></Docs.V2Deprecated> ``` ## Overview The `FormBuilder` component consists of two components that will supply you with all you need to create, preview and render your forms using Abyss form components. To create your form, begin with [FormBuilder.Editor](#formbuildereditor). Once your form is complete, you will use [FormBuilder.Render](#formbuilderrender) to render your completed form. Please see the sections below for further implementation details. ## FormBuilder.Editor ### Usage Use the `FormBuilder.Editor` component to build and preview your forms. When on the Builder tab, you are presented with a matrix/grid-based editor that allows for the construction of your form using a layout that closely mirrors that of the completed form. The primary building block of the form editor consists of a form field widget, which includes the following options: - Add New Component drop-down selector: contains a list of all Abyss form components that are available for selection. - Add toolbar button: provides a drop-down menu with options to add new rows and columns (form fields) to your form. - Delete toolbar button: provides a drop-down menu with options to delete the selected field or delete empty rows. - Note: The `Delete All Empty Rows` option will also delete rows where there is a component placeholder, but a specific component has not been chosen. - Expand toolbar button: expands the currently selected field widget (only one field per row can be opened at a time). - Move Component drop-down selector: contains a list of options to move the component around the form builder. Note: Moving a component up or down will automatically place it at the end of the row. When a field widget is expanded, you will be presented with the tools to configure the selected form field. Starting at the top, there is an interactive preview of the current form field that reflects any changes made from the following Field Configuration tabs: - Props: the applicable props that correspond to the currently selected Abyss form component. For more details on implementation of the props, please see the documentation page that corresponds with the selected component. - Children: currently only applies to Checkbox Group, Radio Group and Toggle Group. This section provides the ability to add child components to the aforementioned parent components. - Layout: configures the layout of the selected field. This section provides the option to allow the form builder to automatically handle the layout, or you can provide the desired responsive settings at the various breakpoints. The layout of the form utilizes the Abyss [Grid](/web/ui/grid) component, so please reference [Responsive (colspan)](/web/ui/grid#responsive-colspan) and [Responsive (percent)](/web/ui/grid#responsive-percent) for more details on implementation. At any point in the form building process, you can click the Preview tab to see the rendered state of your form. This view reflects the final state of the form as it will be viewed and interacted with by the end user. There is a "Submit" button located at the bottom that can be used to test the submission of the form. This view also provides an option for viewing the form in full screen. ```jsx live () => { const [formJson, setFormJson] = useState({}); console.log('current form json', formJson); const handleSubmit = (formData) => { console.log('submitted form data', formData); }; return ( <FormBuilder.Editor title="Form Title" description="Form description goes here" onSubmit={handleSubmit} formJson={formJson} onChange={setFormJson} customLayout={{}} /> ); }; ``` ### Title / description Use the `title` and `description` props to generate pre-styled header content for your form. If you'd like to create custom content at the top or anywhere within your form, it's recommended you use the Rich Text Editor component. To use the Rich Text Editor, select the "Add Form Content" option from the Add New Component drop-down selector located on the Builder. ### formJson & onChange In order to maintain access to the current state of the Form Builder, it's required that you use the combination of the `formJson` and `onChange` props. - The `onChange` prop takes in a state setter function. This prop will continuously be called and return the current form state as a JSON object, which will be used to update the external state. - The `formJson` prop takes in the updated external state provided by the onChange callback or any state you'd like to supply to the Form Builder, such as the JSON from a previously saved form. ### onSubmit The `onSubmit` prop takes in a function that is called whenever the "Submit" button is clicked on the Preview tab. This function will return the submitted form data and exists solely for the purpose of testing the submission behavior and data of the form. ### customLayout The `customLayout` optional prop takes in an object that defines a new default layout for all components inside the FormBuilder. Once applied, individual layouts can then be updated manually in the Layout tab in the Field Configuration section. Here is an example of the object structure that needs to be passed in: ```jsx customLayout={{"xs":"37.5%", "sm":"37.5%", "md":"37.5%", "lg":"37.5%", "xl":"37.5%"}} ``` ### headerButtons Use the `headerButtons` prop to supply custom buttons to the header section of the form editor. `headerButtons` takes in an array of objects with the following structure: - title – button label text - icon – optional icon node that will be placed to the right of the title - onClick – callback function that's fired when clicked and returns the current form JSON state and additional methods for calling form editor actions Note: These buttons will be placed to the right of the built-in "Publish" button if utilized. ```jsx live () => { const initialJson = utils.useFormBuilderJson(); const [formJson, setFormJson] = useState(initialJson); console.log('initial form json', initialJson); console.log('current form json', formJson); const handleSubmit = (formData) => { console.log('submitted form data', formData); }; const headerButtons = [ { title: 'Cancel/Reset', icon: <IconSymbol icon="cancel" variant="outlined" />, onClick: ({ reset }) => { console.log('resetting form'); reset(initialJson); }, }, { title: 'Collapse All', icon: <IconSymbol icon="remove_circle" variant="outlined" />, onClick: ({ collapseAll }) => { collapseAll(); }, }, // Could be used as an alternative to creating a custom Save action that uses the external state of formJson { title: 'Save', icon: <IconSymbol icon="save" variant="outlined" />, onClick: ({ json }) => { console.log('form json', json); }, }, ]; return ( <FormBuilder.Editor formJson={formJson} onChange={setFormJson} onSubmit={handleSubmit} headerButtons={headerButtons} /> ); }; ``` ## FormBuilder.Render The hard work is complete, and now it's time to render your form for usage. The key element to rendering your form is the JSON object that was generated by the `FormBuilder.Editor`. See the [formJson](#formjson) section along with additional details below on how to successfully render your form. ### formJson Supply the JSON object published by the `FormBuilder.Editor` to the `formJson` prop to render the form. ```jsx live () => { const formJson = utils.useFormBuilderJson(); const handleSubmit = (formData) => { console.log('submitted form data', formData); }; return <FormBuilder.Render onSubmit={handleSubmit} formJson={formJson} />; }; ``` ### Form submission `FormBuilder.Render` provides the following two options for handling the submission of the form: #### Default submit (onSubmit) To use the default submission interface, simply provide a callback function to the `onSubmit` prop. A Submit button will automatically be rendered on the UI at the bottom of the form. Upon clicking of the Submit button, the provided callback function will be called, which will return a single argument containing the submitted form data. ```jsx live () => { const formJson = utils.useFormBuilderJson(); const handleSubmit = (formData) => { console.log('submitted form data', formData); }; return <FormBuilder.Render onSubmit={handleSubmit} formJson={formJson} />; }; ``` #### Custom submit (useFormRenderSubmit) ```jsx import { useFormRenderSubmit } from '@uhg-abyss/web/hook/useFormRenderSubmit'; ``` If you prefer to provide a custom UI action to handle the submission of your form, you must use the `useFormRenderSubmit` hook. The hook takes in a single prop, `handleSubmit`, which takes in a callback function that returns the form data upon submission. The hook returns two props: `form` which will need to be passed into `FormBuilder.Render` and `onSubmit` which needs to be called on click of your custom submission button. ```jsx const handleSubmit = (formData) => { console.log('submitted form data', formData); }; const { onSubmit, form } = useFormRenderSubmit({ handleSubmit, }); return ( <Layout.Stack grow> <FormBuilder.Render form={form} formJson={formJson} /> <Button css={{ 'abyss-button-root': { marginTop: '$lg' } }} onClick={onSubmit} > Custom Submit Button </Button> </Layout.Stack> ); ``` ```jsx live () => { const formJson = utils.useFormBuilderJson(); const handleSubmit = (formData) => { console.log('submitted form data', formData); }; const { onSubmit, form } = useFormRenderSubmit({ handleSubmit, }); return ( <Layout.Stack grow> <FormBuilder.Render form={form} formJson={formJson} /> <Button css={{ 'abyss-button-root': { marginTop: '$lg' } }} onClick={onSubmit} > Custom Submit Button </Button> </Layout.Stack> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={FormBuilder.Editor} rows={[ { name: 'title', type: 'string', description: 'Add a title to the form header', }, { name: 'description', type: 'string', description: 'Add a description to the form header', }, { name: 'onSubmit', type: 'function', description: 'Callback fired when clicking "Submit" in Preview tab', }, { name: 'collapseDuration', type: 'number', description: 'Duration of expansion/collapse of form field widget editor', }, { name: 'headerButtons', type: 'array[object]', description: 'Array of custom button configurations to apply to the header of the Builder tab', }, { name: 'customLayout', type: 'object', customLayout: 'Takes in an object that defines a new default layout for all components inside the FormBuilder', }, ]} /> ``` ```jsx render <Docs.PropsTable of={FormBuilder.Render} rows={[ { name: 'formJson', type: 'JSON object', description: 'Add a title of the form header', }, { name: 'form', type: 'object', description: 'Form object returned from useFormRenderSubmit hook when using custom submission', }, { name: 'onSubmit', type: 'function', description: 'Callback fired when clicking default "Submit" button; not applicable when using custom submission', }, { name: 'isPreview', type: 'boolean', description: 'If true, the FormRender component is in preview mode', }, { name: 'theme', type: 'object', description: 'Theme for the FormRender component', }, ]} /> ``` ```jsx render <Docs.PropsTable title="useFormRenderSubmit" rows={[ { name: 'handleSubmit', type: 'function', description: 'Callback fired when custom submission button is clicked', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={FormBuilder.Editor} rows={[ { name: 'form-editor-root', description: 'Form editor root', }, { name: 'form-editor-tabs', description: 'Form editor tabs', }, { name: 'form-editor-builder-tab', description: 'Form editor "Builder" tab', }, { name: 'form-editor-preview-tab', description: 'Form editor "Preview" tab', }, { name: 'form-editor-builder-container', description: 'Form editor "Builder" container', }, { name: 'form-editor-builder-header-container', description: 'Form editor "Builder" header container', }, { name: 'form-editor-builder-publish-button', description: 'Form editor "Builder" publish button', }, { name: 'form-editor-builder-row', description: 'Form editor "Builder" row', }, { name: 'form-editor-builder-row-divider', description: 'Form editor "Builder" row divider', }, { name: 'form-editor-builder-field-widget-container', description: 'Form editor "Builder" field-widget container', }, { name: 'form-editor-builder-field-widget-label', description: 'Form editor "Builder" field-widget label', }, { name: 'form-editor-builder-field-widget-toolbar-container', description: 'Form editor "Builder" field-widget toolbar container', }, { name: 'form-editor-builder-field-widget-toolbar-button', description: 'Form editor "Builder" field-widget toolbar button', }, { name: 'form-editor-builder-field-widget-toolbar-button-icon', description: 'Form editor "Builder" toolbar button icon', }, { name: 'form-editor-builder-field-widget-toolbar-dropdown-button', description: 'Form editor "Builder" field-widget toolbar drop-down button', }, { name: 'form-editor-builder-field-widget-component-selector', description: 'Form editor "Builder" field-widget component drop-down selector', }, { name: 'form-editor-builder-field-editor-container', description: 'Form editor "Builder" field-editor container', }, { name: 'form-editor-builder-field-editor-preview-container', description: 'Form editor "Builder" field-editor preview container', }, { name: 'form-editor-builder-field-editor-tab-group', description: 'Form editor "Builder" field-editor tab group', }, { name: 'form-editor-builder-field-editor-tab', description: 'Form editor "Builder" field-editor tab', }, { name: 'form-editor-builder-field-editor-form-container', description: 'Form editor "Builder" field-editor standard form container', }, { name: 'form-editor-builder-field-editor-form-array-container', description: 'Form editor "Builder" field-editor form-array container', }, { name: 'form-editor-builder-field-editor-form-array-add-button', description: 'Form editor "Builder" field-editor form-array add button', }, { name: 'form-editor-builder-field-editor-form-array-remove-button', description: 'Form editor "Builder" field-editor form-array remove button', }, { name: 'form-editor-builder-field-editor-layout-container', description: 'Form editor "Builder" field-editor layout section container', }, { name: 'form-editor-preview-root', description: 'Form editor "Preview" root', }, { name: 'form-editor-preview-header-container', description: 'Form editor "Preview" header container', }, { name: 'form-editor-preview-header-title', description: 'Form editor "Preview" header title content', }, { name: 'form-editor-preview-header-description', description: 'Form editor "Preview" header description content', }, { name: 'form-editor-preview-grid', description: 'Form editor "Preview" grid', }, { name: 'form-editor-preview-grid-column', description: 'Form editor "Preview" grid column', }, { name: 'form-editor-preview-empty-grid-column', description: 'Form editor "Preview" empty grid column', }, { name: 'form-editor-preview-field-container', description: 'Form editor "Preview" field container', }, { name: 'form-editor-preview-submit-button', description: 'Form editor "Preview" submit button', }, { name: 'form-editor-preview-container', description: 'Form editor "Preview" container', }, { name: 'form-editor-preview-full-screen-button', description: 'Form editor "Preview" full screen button', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={FormBuilder.Render} rows={[ { name: 'form-render-root', description: 'Form root', }, { name: 'form-render-header-container', description: 'Form header container', }, { name: 'form-render-header-title', description: 'Form header title content', }, { name: 'form-render-header-description', description: 'Form header description content', }, { name: 'form-render-grid', description: 'Form grid', }, { name: 'form-render-grid-column', description: 'Form grid column', }, { name: 'form-render-empty-grid-column', description: 'Form empty grid column', }, { name: 'form-render-field-container', description: 'Form field container', }, { name: 'form-render-submit-button', description: 'Form default submit button', }, ]} /> ``` </Tab> --- id: form-provider-v2 category: Providers title: V2FormProvider description: Adds form functionality to Abyss inputs. subDirectory: FormProvider/v2 sourceIsTS: true --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="FormProvider"></Docs.V2MigrationBanner> ``` ```jsx import { V2FormProvider } from '@uhg-abyss/web/ui/FormProvider'; ``` ```jsx render <Docs.FormDisclaimer /> ``` ## Usage Use `V2FormProvider` along with the [useFormV2](/web/hooks/use-form-v2) hook in order to better manage your forms and fully utilize the capabilities of form management within Abyss. To achieve this, you will need to wrap all form fields and the submission button with the `V2FormProvider` component and provide state through the usage of `useFormV2`. Please see examples below for additional props to pass into the `V2FormProvider` and go to [useForm](/web/hooks/use-form-v2) for detailed documentation on how to configure your forms and take advantage of all the available features. Note: The default error message when `required` is `true` is minimally acceptable for accessibility. It is highly recommended to customize it to be more specific to the use of the field and form. ```jsx live () => { const form = useFormV2(); const onSubmit = (data) => { console.log('data', data); // Do something on submit }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2TextInput label="TextInput" placeholder="Form" model="text-input" isClearable validators={{ required: true }} subText="TextInput Subtext" /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ## Highlighted Use the `highlighted` prop to enable a distinct background color when fields are required. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2({}); const onSubmit = (data) => { console.log('data', data); // Do something on submit }; return ( <V2FormProvider state={form} onSubmit={onSubmit} highlighted> <FormSpacing> <V2TextInput label="TextInput Required" model="text-required" validators={{ required: true }} /> <V2TextInput label="TextInput Optional" model="text-optional" /> <V2SelectInput label="SelectInput Required" model="select-required" options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} validators={{ required: true }} /> <V2SelectInput label="SelectInput Optional" model="select-optional" options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> </FormSpacing> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ## Success message Use the `successMessage` prop to provide a default success message to all form input fields. Note: You will be able to override this prop on each form input component if needed with other components that utilize the `successMessage` prop. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2({ defaultValues: { 'text-default': 'John', 'text-custom': 'Doe', 'checkbox-default': true, 'checkbox-custom': true, 'radio-default': 'one', 'radio-custom': 'one', 'checkbox-group-default': ['two'], 'checkbox-group-custom': ['two'], 'text-area-default': 'John', 'text-area-custom': 'Doe', }, }); const onSubmit = (data) => { console.log('data', data); // Do something on submit }; return ( <V2FormProvider state={form} onSubmit={onSubmit} successMessage="Form Provider Default" > <FormSpacing> <V2TextInput label="TextInput (Form Provider Default)" model="text-default" isClearable validators={{ required: true }} /> <V2TextInput label="TextInput (Override Form Provider Default)" model="text-custom" successMessage="Override Form Provider Default" isClearable validators={{ required: true }} /> <V2Checkbox label="Checkbox (Form Provider Default)" model="checkbox-default" validators={{ required: true }} /> <V2Checkbox label="Checkbox (Override Form Provider Default)" model="checkbox-custom" successMessage="Override Form Provider Default" validators={{ required: true }} /> <V2RadioGroup label="RadioGroup (Form Provider Default)" model="radio-default" validators={{ required: true }} > <V2RadioGroup.Column> <V2RadioGroup.Radio label="One" value="one" /> <V2RadioGroup.Radio label="Three" value="three" /> </V2RadioGroup.Column> </V2RadioGroup> <V2RadioGroup label="RadioGroup (Override Form Provider Default)" model="radio-custom" successMessage="Override Form Provider Default" validators={{ required: true }} > <V2RadioGroup.Column> <V2RadioGroup.Radio label="One" value="one" /> <V2RadioGroup.Radio label="Three" value="three" /> </V2RadioGroup.Column> </V2RadioGroup> <V2CheckboxGroup label="CheckboxGroup (Form Provider Default)" model="checkbox-group-default" validators={{ required: true }} > <V2CheckboxGroup.Column> <V2Checkbox label="Option 1" value="one" /> <V2Checkbox label="Option 2" value="two" /> <V2Checkbox label="Option 3" value="three" /> </V2CheckboxGroup.Column> </V2CheckboxGroup> <V2CheckboxGroup label="CheckboxGroup (Override Form Provider Default)" model="checkbox-group-custom" successMessage="Override Form Provider Default" validators={{ required: true }} > <V2CheckboxGroup.Column> <V2Checkbox label="Option 1" value="one" /> <V2Checkbox label="Option 2" value="two" /> <V2Checkbox label="Option 3" value="three" /> </V2CheckboxGroup.Column> </V2CheckboxGroup> <V2TextInputArea label="TextInputArea (Form Provider Default)" model="text-area-default" isClearable validators={{ required: true }} /> <V2TextInputArea label="TextInputArea (Override Form Provider Default)" model="text-area-custom" successMessage="Override Form Provider Default" isClearable validators={{ required: true }} /> </FormSpacing> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2FormProvider" propTypeName="FormProviderProps" showAbyssDefaultTypes /> ``` </Tab> --- id: form-provider category: Providers title: FormProvider description: Adds form functionality to Abyss inputs. subDirectory: FormProvider/v1 --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="FormProvider"></Docs.V2MigrationBanner> ``` ```jsx import { FormProvider } from '@uhg-abyss/web/ui/FormProvider'; ``` ## Usage Use `FormProvider` along with the [useForm](/web/hooks/use-form) hook in order to better manage your forms and fully utilize the capabilities of form management within Abyss. To achieve this you will need to wrap all form fields and the submission button with the `FormProvider` component and provide state through usage of `useForm`. Please see examples below for additional props to pass into the `FormProvider` and go to [useForm](/web/hooks/use-form) for detailed documentation on how to configure your forms and take advantage of all the available features. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); // Do something on submit }; return ( <FormProvider state={form} onSubmit={onSubmit}> <Checkbox label="I agree to the Terms and Conditions" model="accept-terms" validators={{ required: true }} /> <SelectInput label="Select List Usage" model="selectlist" placeholder="Select List Form Provider" options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} validators={{ required: true }} /> <Button type="submit" style={{ marginTop: '15px' }}> Submit </Button> </FormProvider> ); }; ``` ## Highlighted Use the `highlighted` prop to enable a distinct background color when fields are required. ```jsx live () => { const form = useForm({ defaultValues: { // selectlist: 'ember', // frameworks: ['ember', 'svelte'], // 'test-date': '05/14/1993', // textForm: 'test', // 'test-form-date': { from: '06/04/2022', to: '06/30/2022' }, }, }); const onSubmit = (data) => { console.log('data', data); // Do something on submit }; const options = [ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]; return ( <FormProvider state={form} onSubmit={onSubmit} highlighted> <SelectInput label="Select List Usage" model="selectlist" placeholder="Select List Form Provider" options={options} validators={{ required: true }} /> <SelectInputMulti label="Your favorite framework/library" placeholder="Pick one" model="frameworks" isSearchable options={options} validators={{ required: true }} /> <DateInput model="test-date" validators={{ required: true }} /> <DateInputRange model="test-form-date" validators={{ required: true }} /> <TextInput label="TextInput Form" placeholder="Form" model="textForm-required" isClearable validators={{ required: true }} /> <TextInput label="TextInput Form Not Required" placeholder="Form" model="textForm" isClearable /> <Button type="submit" style={{ marginTop: '15px' }}> Submit </Button> </FormProvider> ); }; ``` ## Descriptors display Use the `descriptorsDisplay` prop to set the orientation of the error message and subtext descriptor content across the entire form. Available variants include 'column' and 'row'. If no value is included the orientation will default to row. If `descriptorsDisplay` is used within the FormProvider it will override any setting within an individual form field. Please note that for accessibility compliance the error message must always display before the subtext. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); // Do something on submit }; const options = [ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]; return ( <FormProvider state={form} onSubmit={onSubmit} descriptorsDisplay="column"> <SelectInput label="SelectInput" model="select-input" placeholder="Select List Form Provider" options={options} validators={{ required: true }} subText="SelectInput Subtext" /> <DateInput label="DateInput" model="test-date" validators={{ required: true }} /> <TextInput label="TextInput" placeholder="Form" model="text-input" isClearable validators={{ required: true }} subText="TextInput Subtext" /> <CheckboxGroup label="CheckboxGroup" model="checkbox-group" display="row" validators={{ required: true }} subText="CheckboxGroup Subtext" > <Checkbox label="Option 1" value="one" /> <Checkbox label="Option 2" value="two" /> <Checkbox label="Option 3" value="three" /> </CheckboxGroup> <RadioGroup label="RadioGroup" model="radio-group" display="row" validators={{ required: true }} subText="RadioGroup Subtext" > <RadioGroup.Radio label="One" value="one" /> <RadioGroup.Radio label="Two" value="two" /> <RadioGroup.Radio label="Three" value="three" /> <RadioGroup.Radio label="Four" value="four" /> </RadioGroup> <TextInputArea label="TextInputArea" model="text-input-area" validators={{ required: true }} subText="TextInputArea Subtext" /> <Button type="submit" style={{ marginTop: '15px' }}> Submit </Button> </FormProvider> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={FormProvider} rows={[ { name: 'state', type: 'object', description: 'State passed in from useForm.', }, { name: 'children', type: 'ReactNode', description: 'Form inputs passed to FormProvider', }, { name: 'onSubmit', type: 'function', description: 'Callback fired when type="submit" button within the FormProvider wrapper is triggered', }, { name: 'onError', type: 'function', description: 'Callback fired when type="error" button within the FormProvider wrapper is triggered', }, { name: 'autoComplete', type: 'string', description: 'The autocomplete status that is passed to the form element in the FormProvider', }, { name: 'highlighted', type: 'boolean', description: 'Enables a distinct background color when fields are invalid', }, { name: 'descriptorsDisplay', type: '"row" | "column"', description: 'Set the orientation of descriptor content across the entire form', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={FormProvider} rows={[ { name: 'Form-provider-root', description: 'Form Provider root element', }, ]} /> ``` </Tab> --- id: fullscreen category: Overlay title: Fullscreen description: Displays an overlay that takes up the entire screen. --- <Tab label="Overview"> ```jsx render <Docs.V2Deprecated componentName="Fullscreen" /> ``` ```jsx render <Docs.V2MigrationBanner v1ComponentName="Fullscreen" /> ``` ```jsx import { Fullscreen } from '@uhg-abyss/web/ui/Fullscreen'; ``` ```jsx sandbox { component: 'Fullscreen', inputs: [ { prop: 'children', type: 'string', }, { prop: 'title', type: 'string', }, ], } () => { const [isOpen, setIsOpen] = useState(false); return ( <React.Fragment> <Fullscreen title="Enter title here" isOpen={isOpen} onClose={() => setIsOpen(false)} > Press escape to close the fullscreen </Fullscreen> <Button onClick={() => setIsOpen(true)}> Toggle Fullscreen </Button> </React.Fragment> ); } ``` ## useOverlay Using the `useOverlay` hook lets the DOM handle form data and the overlays state. To utilize the [useOverlay](/web/hooks/use-overlay) hook the root/parent must be wrapped with the [OverlayProvider](/web/ui/overlay-provider). ```jsx live () => { const fullscreen = useOverlay('fullscreen-form'); const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( <React.Fragment> <Button onClick={() => fullscreen.open()}>Toggle Fullscreen</Button> <FormProvider state={form} onSubmit={onSubmit}> <Fullscreen title="Register" model="fullscreen-form"> <Fullscreen.Section> <TextInput label="First Name" model="first-name" validators={{ required: true }} /> <TextInput label="Last Name" model="last-name" validators={{ required: true }} /> <TextInput label="Email" type="email" model="email" validators={{ required: true }} /> <TextInput label="Password" type="password" model="password" validators={{ required: true }} /> <div style={{ marginTop: 20, marginBottom: 20 }}> <Checkbox label="I agree to terms and conditions" model="terms-condition" validators={{ required: true }} /> </div> </Fullscreen.Section> <Fullscreen.Section> <Layout.Group alignLayout="right"> <Button variant="outline" onClick={() => fullscreen.close()}> Cancel </Button> <Button onClick={() => { form.handleSubmit(onSubmit)(); if (form.formState.isValid) { fullscreen.close(); } }} > Submit </Button> </Layout.Group> </Fullscreen.Section> </Fullscreen> </FormProvider> </React.Fragment> ); }; ``` ## useState Using the `useState` hook to set the open state of the fullscreen. ```jsx live () => { const [isOpen, setIsOpen] = useState(false); const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( <React.Fragment> <Button onClick={() => setIsOpen(true)}>Toggle Fullscreen</Button> <FormProvider state={form} onSubmit={onSubmit}> <Fullscreen title="Register" isOpen={isOpen} onClose={() => setIsOpen(false)} > <Fullscreen.Section> <TextInput label="First Name" model="first-name" validators={{ required: true }} /> <TextInput label="Last Name" model="last-name" validators={{ required: true }} /> <TextInput label="Email" type="email" model="email" validators={{ required: true }} /> <TextInput label="Password" type="password" model="password" validators={{ required: true }} /> <div style={{ marginTop: 20, marginBottom: 20 }}> <Checkbox label="I agree to terms and conditions" model="terms-condition" validators={{ required: true }} /> </div> </Fullscreen.Section> <Fullscreen.Section> <Layout.Group alignLayout="right"> <Button onClick={() => setIsOpen(false)} variant="outline"> Cancel </Button> <Button onClick={() => setIsOpen(false)}>Submit</Button> </Layout.Group> </Fullscreen.Section> </Fullscreen> </FormProvider> </React.Fragment> ); }; ``` ## Title Use the `title` prop to set the title of the fullscreen. ```jsx live () => { const fullscreen = useOverlay('title-fullscreen'); return ( <React.Fragment> <Button onClick={() => fullscreen.open()}>Toggle Fullscreen</Button> <Fullscreen title="Custom Title" model="title-fullscreen"> <Fullscreen.Section>Custom Title</Fullscreen.Section> </Fullscreen> </React.Fragment> ); }; ``` ## Passing data Use the `getState` method retrieve the state of the fullscreen. Structure: `{ isOpen: Boolean, data: Object }`. Pass data into the open/toggle methods to use in the fullscreen. ```jsx live () => { const fullscreen = useOverlay('data-fullscreen'); const { data } = fullscreen.getState(); return ( <React.Fragment> <Button onClick={() => fullscreen.open({ firstName: 'John', lastName: 'Doe' })} > Toggle Fullscreen </Button> <Fullscreen title="Passing Data to Fullscreen" model="data-fullscreen"> <Fullscreen.Section> <p>First Name: {data && data.firstName}</p> <p>Last Name: {data && data.lastName}</p> </Fullscreen.Section> </Fullscreen> </React.Fragment> ); }; ``` ## Title align Use the `titleAlign` prop to align the position of the title. ```jsx live () => { const form = useForm(); const fullscreen = useOverlay('title-aligment'); const [align, setAlign] = useState('left'); const onSubmit = (data) => { console.log('data', data); }; return ( <React.Fragment> <Layout.Group> <Button onClick={() => { fullscreen.open(); setAlign('left'); }} > Left </Button> <Button onClick={() => { fullscreen.open(); setAlign('center'); }} > Center </Button> <Button onClick={() => { fullscreen.open(); setAlign('right'); }} > Right </Button> </Layout.Group> <FormProvider state={form} onSubmit={onSubmit}> <Fullscreen title="Title Alignment" position="top" titleAlign={align} model="title-aligment" > <Fullscreen.Section>Title Alignment</Fullscreen.Section> </Fullscreen> </FormProvider> </React.Fragment> ); }; ``` ## Overflow Overflow is handled within the content of the fullscreen. The title will remain static. ```jsx live () => { const fullscreen = useOverlay('overflow-fullscreen'); const topRef = useRef(null); return ( <React.Fragment> <Button onClick={() => fullscreen.open()}>Toggle Fullscreen</Button> <Fullscreen title="Overflow" model="overflow-fullscreen" scrollableFocus={true} > <div ref={topRef}> </div> <Fullscreen.Section> {Array.from(Array(50).keys()).map((item) => { return ( <p key={item} style={{ marginBottom: 65 }}> Overflow Example - Scroll </p> ); })} <Layout.Group alignLayout="right"> <Button onClick={() => topRef.current.scrollIntoView({ behavior: 'smooth' }) } > Back to Top </Button> </Layout.Group> </Fullscreen.Section> </Fullscreen> </React.Fragment> ); }; ``` ## Footer Use the `footer` to add a footer container to a fullscreen. ```jsx live () => { const fullscreen = useOverlay('fullscreen-footer'); const topRef = useRef(null); return ( <React.Fragment> <Button onClick={() => fullscreen.open()}>Toggle Fullscreen</Button> <Fullscreen title="Fullscreen With Footer " model="fullscreen-footer" scrollableFocus={true} footer={ <Fullscreen.Section> <Layout.Group alignLayout="right"> <Button onClick={() => fullscreen.close()}>Cancel</Button> <Button onClick={() => topRef.current.scrollIntoView({ behavior: 'smooth' }) } > Back to Top </Button> </Layout.Group> </Fullscreen.Section> } > <div ref={topRef}> </div> <Fullscreen.Section> {Array.from(Array(30).keys()).map((item) => { return ( <p key={item} style={{ marginBottom: 65 }}> Fullscreen footer with cancel button </p> ); })} </Fullscreen.Section> </Fullscreen> </React.Fragment> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={Fullscreen} rows={[ { name: 'children', type: 'ReactNode', description: 'The contents of the Fullscreen component', }, { name: 'footer', type: 'node', description: 'The contents of the Fullscreen footer', }, { name: 'title', type: 'string', description: 'Set the title of the fullscreen', }, { name: 'ariaLabel', type: 'string', description: 'Set the ariaLabel of fullscreen', }, { name: 'isOpen', type: 'boolean', description: 'Flag to check if fullscreen is opened', }, { name: 'onClose', type: 'function', description: 'Callback fired everytime fullscreen is closed', }, { name: 'model', type: 'string', description: 'Unique identifier used for FormProvider', }, { name: 'titleAlign', type: 'string', description: 'Set the alignment of the title', }, { name: 'headerAction', type: 'ReactNode', description: 'Should be utilized in cases where a title is not provided and a component that includes a focusable element needs to be supplied to the header portion of the Fullscreen. This element will receive initial focus rather than the close button', }, ]} /> ``` ```jsx render <Docs.PropsTable of={Fullscreen.Section} rows={[ { name: 'children', type: 'ReactNode', description: 'The contents of the Fullscreen Section component', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Fullscreen} rows={[ { name: 'modal-root', description: 'Fullscreen root element', }, { name: 'modal-overlay', description: 'Fullscreen overlay element', }, { name: 'modal-content-container', description: 'Fullscreen content container', }, { name: 'modal-header-container', description: 'Fullscreen header container', }, { name: 'modal-header-title', description: 'Fullscreen title element', }, { name: 'modal-body', description: 'Fullscreen body element', }, { name: 'modal-footer', description: 'Fullscreen footer element', }, { name: 'modal-close-button', description: 'Fullscreen close button element', }, { name: 'modal-close-icon', description: 'Fullscreen close icon element', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Fullscreen.Section} rows={[ { name: 'modal-section-root', description: 'Fullscreen Section root element', }, ]} /> ``` </Tab> <Tab label="Accessibility"> ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Esc', description: 'Closes the Fullscreen.', }, { name: 'Tab', description: 'Moves focus to the next interactive element within the Fullscreen. Once the last interactive element in the Fullscreen is reached, pressing Tab again moves focus to the first interactive element within the Fullscreen.', }, { name: 'Shift + Tab', description: 'Moves focus to the previous interactive element within the Fullscreen. Once the first interactive element in the Fullscreen is reached, pressing Shift + Tab again moves focus to the last interactive element within the Fullscreen.', }, ]} /> ``` <h3>Fullscreen Accessible Example</h3> ```jsx live () => { const fullscreen = useOverlay('overflow-fullscreen'); const topRef = useRef(null); return ( <React.Fragment> <Button onClick={() => fullscreen.open()}>Show Fullscreen</Button> <Fullscreen title="Accessible Fullscreen with overflow content" model="overflow-fullscreen" scrollableFocus={true} > <div ref={topRef}> </div> <Fullscreen.Section> {Array.from(Array(50).keys()).map((item) => { return ( <p key={item} style={{ marginBottom: 65 }}> Meaningless text to fill screen and force the creation of a scrolling region. </p> ); })} <Layout.Group alignLayout="right"> <Button onClick={() => topRef.current.scrollIntoView({ behavior: 'smooth' }) } > Back to top </Button> </Layout.Group> </Fullscreen.Section> </Fullscreen> </React.Fragment> ); }; ``` <h3>Fullscreen Content</h3> When creating a fullscreen component it is important to ensure that the content is accessible. The content should be structured in a way that is easy to navigate and understand. Avoid static scrolling, and jumping to or from content. This can cause issues for users who rely on screen readers to understand the content of a page. Instead include keyboard options to ensure all users can scroll through all content. For further information about creating accessible fullscreen content, please refer to the following resources: <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/">Dialog (Modal) Pattern</ExitLink> | <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/dialog/">Dialog (Modal) Example</ExitLink> ```jsx live () => { const fullscreen = useOverlay('accessible-fullscreen'); return ( <> <Button onClick={() => fullscreen.open()}>Toggle Fullscreen</Button> <Fullscreen title="Accessible Fullscreen" model="accessible-fullscreen"> <Fullscreen.Section> <Button>Button is accessible in fullscreen</Button> </Fullscreen.Section> </Fullscreen> </> ); }; ``` </Tab> --- id: grid category: Layout title: Grid description: Provides a brief message about the app processes. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=3-16551 --- <Tab label="Overview"> ```jsx import { Grid } from '@uhg-abyss/web/ui/Grid'; ``` ## Live example Resizing the width of the screen changes the column width, making Grid responsive. ```jsx live () => { const cardCssStyles = { 'abyss-card-root': { height: '100%', display: 'flex', flexDirection: 'column', '.abyss-card-section:first-child': { flexGrow: 1, }, }, }; return ( <Grid> <Grid.Col span={{ xs: 9, md: 9, lg: 6, xl: 6 }}> <Heading>Better Data With Seamless Integrations</Heading> <Text> Find, Integrate and Manage your United Healthcare APIs all in one place. Save time and money by getting more useful information on your United Healthcare members integrated with your current workflows. </Text> </Grid.Col> <Grid.Col span={{ xs: 3, md: 3, lg: 6, xl: 6 }}></Grid.Col> <Grid.Col span={{ xs: 12, md: 6, lg: 6, xl: 6 }}> <Card css={cardCssStyles}> <Card.Section> <IconBrand color="$primary1" icon="desktop" size={48} /> <Heading offset={2}>Admin</Heading> <Text size="$sm"> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse porta vel est egestas finibus. Cras cursus ante nisi, ac feugiat arcu dapibus pretium. Mauris posuere elementum tellus a fringilla. Vivamus vitae nulla in lorem sodales tristique ac sit amet lorem. Quisque euismod, ligula at pretium bibendum, justo justo porttitor ex, et interdum velit nisi quis felis. In egestas dui dui, eu elementum sapien convallis eget. </Text> </Card.Section> <Card.Section> <Link href="/web/developers/overview">Link Button</Link> </Card.Section> </Card> </Grid.Col> <Grid.Col span={{ xs: 12, md: 6, lg: 6, xl: 6 }}> <Card css={cardCssStyles}> <Card.Section> <IconBrand color="$primary1" icon="bar_chart" size={48} /> <Heading offset={2}>Analytics</Heading> <Text size="$sm"> Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt… </Text> </Card.Section> <Card.Section> <Link href="/web/developers/overview">Link Button</Link> </Card.Section> </Card> </Grid.Col> <Grid.Col span={{ xs: 12, md: 6, lg: 6, xl: 6 }}> <Card css={cardCssStyles}> <Card.Section> <IconBrand color="$primary1" icon="heart" size={48} /> <Heading offset={2}>Clinical</Heading> <Text size="$sm"> Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt… </Text> </Card.Section> <Card.Section> <Link href="/web/developers/overview">Link Button</Link> </Card.Section> </Card> </Grid.Col> <Grid.Col span={{ xs: 12, md: 6, lg: 6, xl: 6 }}> <Card css={cardCssStyles}> <Card.Section> <IconBrand color="$primary1" icon="piggy_bank" size={48} /> <Heading offset={2}>Financial</Heading> <Text size="$sm"> Praesent ultrices aliquam lorem vitae mollis. Cras eleifend ligula sed mi aliquam, eget pulvinar ipsum interdum. Proin imperdiet leo a leo laoreet vestibulum. Sed et viverra sapien. Pellentesque viverra cursus tempus. </Text> </Card.Section> <Card.Section> <Link href="/web/developers/overview">Link Button</Link> </Card.Section> </Card> </Grid.Col> <Grid.Col span={{ xs: 12, md: 12, lg: 12, xl: 12 }}> <Heading>Newest API's</Heading> </Grid.Col> <Grid.Col span={{ xs: 12, md: 6, lg: 6, xl: 6 }}> <Card css={cardCssStyles}> <Card.Section> <Heading offset={2}>Claims</Heading> <Text> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed dignissim felis id justo scelerisque pharetra. Maecenas porta, massa sit amet sagittis suscipit, sem velit blandit lectus, nec pharetra magna ligula id ligula. Quisque feugiat nulla mi, mollis varius mauris auctor a. Nullam odio mi, aliquet sed tincidunt et, ultrices et mi. </Text> </Card.Section> <Card.Section> <Link href="/web/developers/overview">Link Button</Link> </Card.Section> </Card> </Grid.Col> <Grid.Col span={{ xs: 12, md: 6, lg: 6, xl: 6 }}> <Card css={cardCssStyles}> <Card.Section> <Heading offset={2}>Services</Heading> <Text> Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt… </Text> </Card.Section> <Card.Section> <Link href="/web/developers/overview">Link Button</Link> </Card.Section> </Card> </Grid.Col> </Grid> ); }; ``` ## Unresponsive (colspan) Regardless of viewport width, the span will remain the same for these columns. Change the span by using [column spans] of the parent container. ```jsx live <Grid> <Grid.Col span={12}> <Box color="$tint3"> <Heading offset={5}>12</Heading> </Box> </Grid.Col> <Grid.Col span={3}> <Box color="$tint3"> <Heading offset={5}>3</Heading> </Box> </Grid.Col> <Grid.Col span={3}> <Box color="$tint3"> <Heading offset={5}>3</Heading> </Box> </Grid.Col> <Grid.Col span={3}> <Box color="$tint3"> <Heading offset={5}>3</Heading> </Box> </Grid.Col> <Grid.Col span={3}> <Box color="$tint3"> <Heading offset={5}>3</Heading> </Box> </Grid.Col> <Grid.Col span={6}> <Box color="$tint3"> <Heading offset={5}>6</Heading> </Box> </Grid.Col> <Grid.Col span={6}> <Box color="$tint3"> <Heading offset={5}>6</Heading> </Box> </Grid.Col> </Grid> ``` ## Unresponsive (percent) Regardless of viewport width, the span will remain the same for these columns. Change the span by using percentages of the parent container. ```jsx live <Grid> <Grid.Col span="100%"> <Box color="$tint3"> <Heading offset={5}>100%</Heading> </Box> </Grid.Col> <Grid.Col span="33%"> <Box color="$tint3"> <Heading offset={5}>33%</Heading> </Box> </Grid.Col> <Grid.Col span="33%"> <Box color="$tint3"> <Heading offset={5}>33%</Heading> </Box> </Grid.Col> <Grid.Col span="33%"> <Box color="$tint3"> <Heading offset={5}>33%</Heading> </Box> </Grid.Col> <Grid.Col span="20%"> <Box color="$tint3"> <Heading offset={5}>20%</Heading> </Box> </Grid.Col> <Grid.Col span="20%"> <Box color="$tint3"> <Heading offset={5}>20%</Heading> </Box> </Grid.Col> <Grid.Col span="20%"> <Box color="$tint3"> <Heading offset={5}>20%</Heading> </Box> </Grid.Col> <Grid.Col span="20%"> <Box color="$tint3"> <Heading offset={5}>20%</Heading> </Box> </Grid.Col> <Grid.Col span="20%"> <Box color="$tint3"> <Heading offset={5}>20%</Heading> </Box> </Grid.Col> </Grid> ``` ## Responsive (colspan) At each breakpoint, these columns will resize the span based on colspan. Breakpoints are `xs, sm, md, lg, and xl`. ```jsx live <Grid> <Grid.Col span={{ xs: 12, md: 6 }}> <Box color="$tint3"> <Heading offset={5}>Responsive</Heading> </Box> </Grid.Col> <Grid.Col span={{ xs: 12, md: 6 }}> <Box color="$tint3"> <Heading offset={5}>Responsive</Heading> </Box> </Grid.Col> <Grid.Col span={{ xs: 12, md: 6, lg: 3, xl: 3 }}> <Box color="$tint3"> <Text>Responsive</Text> </Box> </Grid.Col> <Grid.Col span={{ xs: 12, md: 6, lg: 3, xl: 3 }}> <Box color="$tint3"> <Text>Responsive</Text> </Box> </Grid.Col> <Grid.Col span={{ xs: 12, md: 6, lg: 3, xl: 3 }}> <Box color="$tint3"> <Text>Responsive</Text> </Box> </Grid.Col> <Grid.Col span={{ xs: 12, md: 6, lg: 3, xl: 3 }}> <Box color="$tint3"> <Text>Responsive</Text> </Box> </Grid.Col> </Grid> ``` ## Responsive (percent) At each breakpoint, these columns will resize the span based on percentage of the parent container. Breakpoints are `xs, sm, md, lg, and xl`. ```jsx live <Grid> <Grid.Col span={{ xs: '100%', md: '50%' }}> <Box color="$tint3"> <Heading offset={5}>Responsive</Heading> </Box> </Grid.Col> <Grid.Col span={{ xs: '100%', md: '50%' }}> <Box color="$tint3"> <Heading offset={5}>Responsive</Heading> </Box> </Grid.Col> <Grid.Col span={{ xs: '100%', md: '50%', lg: '25%', xl: '33%' }}> <Box color="$tint3"> <Text>Responsive</Text> </Box> </Grid.Col> <Grid.Col span={{ xs: '100%', md: '50%', lg: '25%', xl: '33%' }}> <Box color="$tint3"> <Text>Responsive</Text> </Box> </Grid.Col> <Grid.Col span={{ xs: '100%', md: '50%', lg: '25%', xl: '33%' }}> <Box color="$tint3"> <Text>Responsive</Text> </Box> </Grid.Col> <Grid.Col span={{ xs: '100%', md: '50%', lg: '25%', xl: '33%' }}> <Box color="$tint3"> <Text>Responsive</Text> </Box> </Grid.Col> </Grid> ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={Grid} rows={[ { name: 'children', type: 'ReactNode', description: 'The contents of the grid component', }, { name: 'columns', type: 'number', description: 'XL and L are 12-column, MD is 9-column, SM is 6-column and XS is 4-column.', }, { name: 'space', type: 'number | shape', description: 'Automatically updates based on screen size.', }, { name: 'align', type: 'string', description: '', }, { name: 'justify', type: 'string', description: '', }, { name: 'span', type: 'number | string | shape', description: 'Handles the span size of the grid', }, { name: 'noWrap', type: 'boolean', default: 'false', description: 'turns wrap on and off', }, ]} /> ``` ```jsx render <Docs.PropsTable of={Grid.Col} rows={[ { name: 'children', type: 'ReactNode', description: 'The contents of the grid col component', }, { name: 'span', type: 'number | string | shape', description: 'Handles the span size of the column', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Grid} rows={[ { name: 'grid', description: 'Grid root element', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Grid.Col} rows={[ { name: 'grid-col', description: 'Grid column element', }, ]} /> ``` </Tab> --- id: header-v2 category: Content title: V2Header description: Used to create a page header. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=24-12784 sourceIsTS: true subDirectory: Header --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="PageHeaderPrimitives"></Docs.V2MigrationBanner> ``` ```jsx import { V2Header } from '@uhg-abyss/web/ui/Header'; ``` ## Container Use the `Container` subcomponent of `V2Header` to wrap all other elements in the Header. ```jsx live <V2Header.Container> <V2Header.Brandmark /> </V2Header.Container> ``` ## Brandmark Use the `Brandmark` subcomponent of `V2Header` to customize brand mark in page header. Clicking on it will trigger a redirect to the home page. Below are the props for Brandmark subcomponent. ```jsx live () => { return ( <> <V2Header.Container css={{ 'abyss-page-header-root': { zIndex: 100, }, }} > <V2Header.Brandmark /> </V2Header.Container> </> ); }; ``` `logo` - prop to provide the logo that will be displayed on the far left side of the header. By default, it will show either the UHC, UHG or Optum logo, depending on the page theme. ```jsx live () => { const abyss = utils.useBaseUrl('/img/logo.svg'); return ( <> <V2Header.Container css={{ 'abyss-page-header-root': { zIndex: 100, }, }} > <V2Header.Brandmark logo={ <Flex direction="column" alignItems="center"> <Box height="50px" width="50px" padding="0px" css={{ 'abyss-box-root': { backgroundImage: `url(${abyss})`, backgroundRepeat: 'no-repeat', backgroundSize: 'cover', backgroundColor: 'transparent', }, }} /> <Text>Abyss Logo</Text> </Flex> } /> </V2Header.Container> </> ); }; ``` ## Main content Use the `MainContent` subcomponent of `V2Header` to wrap the main content of the header. This is useful for adding additional elements like relevant buttons or other interactive components that will be placed on the right of the Brandmark. ```jsx live () => { return ( <V2Header.Container> <V2Header.Brandmark /> <V2Header.MainContent> <V2Button variant="text" icon={{ icon: 'mail', position: 'leading', variant: 'outlined' }} onClick={() => console.log('Messages clicked')} > Messages </V2Button> <V2Button variant="text" icon={{ icon: 'notifications', position: 'leading', variant: 'outlined', }} onClick={() => console.log('Notifications clicked')} > Notifications </V2Button> </V2Header.MainContent> </V2Header.Container> ); }; ``` ## Utility bar Use the `UtilityBar` subcomponent of `V2Header` inside the `Provider` to show any additional content on the top header. This is an "open" container, where you can place utility dropdowns and links. The example below showcases its use with our `V2Dropdown` and `V2Link` components. ```jsx live () => { const menuItems = [ { title: 'English', onClick: () => { console.log('English chosen'); }, }, { title: 'Español', onClick: () => { console.log('Elegiste Español'); }, }, ]; return ( <> <V2Header.UtilityBar> <ul style={{ display: 'flex', flexDirection: 'row', gap: 20, alignItems: 'center', }} > <li> <V2DropdownMenu label="Language" menuItems={menuItems} outline={false} /> </li> <li> <V2Link size="$md" href=""> Help </V2Link> </li> </ul> </V2Header.UtilityBar> <V2Header.Container css={{ 'abyss-page-header-root': { zIndex: 100, }, }} > <V2Header.Brandmark /> </V2Header.Container> </> ); }; ``` ## Actions Use the `Actions` subcomponent of `V2Header` to show any additional content on the right side of the header. This is an "open" container that takes any children, such as a search box, buttons, or a set of links that provide secondary actions. The example below showcases its use with our `DropdownMenu` component. ```jsx live () => { const menuItems = [ { title: 'Profile', onClick: () => { console.log('Clicked Profile'); }, }, { title: 'Settings', onClick: () => { console.log('Clicked Settings'); }, }, { title: 'Log Out', onClick: () => { console.log('Clicked Log Out'); }, }, ]; return ( <V2Header.Container css={{ 'abyss-page-header-root': { zIndex: 100, }, }} > <V2Header.Brandmark /> <V2Header.Actions> <V2DropdownMenu label="Account" menuItems={menuItems} outline={false} /> </V2Header.Actions> </V2Header.Container> ); }; ``` ## V2Header + V2NavMenu When using these two components together, the `V2NavMenu` needs to be wrapped around the `V2Header.Navigation` subcomponent. This ensures that the `V2NavMenu` has a responsive design, and "hides" on mobile screens (Note: The content is still rendered into the DOM for SEO purposes). The `V2Header.Navigation` has a prop `sticky` that can be set to `true` to make the header navigation container sticky at the top of the viewport, or you can pass your own custom CSS properties. Additionally, adding the `V2Header.HamburgerMenu` in to the `V2Header.Actions` component allows you to have an external state trigger to display/hide the mobile version of `V2Navmenu` Here is an example for usage of the `V2Header` and `V2NavMenu` subcomponents (Note: Resize your browser window to visualize the change): ```jsx live () => { const [isOpen, setIsOpen] = useState(false); const menuItems = [ { title: 'Profile', onClick: () => { console.log('Clicked Profile'); }, }, { title: 'Settings', onClick: () => { console.log('Clicked Settings'); }, }, { title: 'Log Out', onClick: () => { console.log('Clicked Log Out'); }, }, ]; const DropdownMenuContent = () => { return ( <V2NavMenu.Columns> <V2NavMenu.Column title="Section Title"> <V2NavMenu.MenuItem title="HELLO" href="https://abyss.uhc.com/"> CSS-in-JS with best-in-class developer experience. </V2NavMenu.MenuItem> <V2NavMenu.MenuItem title="GOODBYE" href="https://abyss.uhc.com/" description="Description goes here" /> </V2NavMenu.Column> <V2NavMenu.Column> <V2NavMenu.MenuItem title="Sample onClick" onClick={() => console.log('onClick pressed')} description="A message will be logged to the console when this is clicked." /> </V2NavMenu.Column> <V2NavMenu.Column title="Other Section Title"> <V2NavMenu.MenuItem title="Colors" href="#" description="Description goes here" /> <V2NavMenu.MenuItem title="Colors" href="#" description="Description goes here" /> <V2NavMenu.MenuItem title="Colors" href="#" description="Description goes here" /> </V2NavMenu.Column> </V2NavMenu.Columns> ); }; return ( <> <V2Header.Container css={{ 'abyss-page-header-root': { zIndex: 100, }, }} > <V2Header.Brandmark /> <V2Header.Actions> <V2DropdownMenu label="Account" menuItems={menuItems} outline={false} css={{ 'abyss-dropdown-menu-trigger': { backgroundColor: '$header-v2.color.background.container', }, }} /> <V2Header.HamburgerMenu onClick={() => { setIsOpen(!isOpen); }} type="button" aria-label="Menu" aria-haspopup="dialog" > <IconSymbol icon={isOpen ? 'close' : 'menu'} /> </V2Header.HamburgerMenu> </V2Header.Actions> </V2Header.Container> <V2Header.Navigation menuActive={isOpen}> <V2NavMenu.Root> <V2NavMenu.List> <V2NavMenu.Link href="">Dashboard</V2NavMenu.Link> <V2NavMenu.Item> <V2NavMenu.Trigger>Coverage & Benefits</V2NavMenu.Trigger> <V2NavMenu.Content> <DropdownMenuContent /> </V2NavMenu.Content> </V2NavMenu.Item> <V2NavMenu.Item> <V2NavMenu.Trigger>Health & Wellness</V2NavMenu.Trigger> <V2NavMenu.Content> <DropdownMenuContent /> </V2NavMenu.Content> </V2NavMenu.Item> </V2NavMenu.List> </V2NavMenu.Root> </V2Header.Navigation> </> ); }; ``` ## Full layout Shows a combination of the `V2Header` and the `V2NavMenu` in a full page. Note: the `sticky` prop in the `V2Header.Navigation` is set to true in this example. ```jsx live <V2Link href="/v2fullpagelayout" openNewWindow> Full Page Layout </V2Link> ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2Header.Container" propTypeName="V2HeaderContainerProps" /> ``` ```jsx render <Docs.V2WebPropsTable title="V2Header.Brandmark" propTypeName="V2HeaderBrandmarkProps" /> ``` ```jsx render <Docs.V2WebPropsTable title="V2Header.MainContent" propTypeName="V2HeaderMainContentProps" /> ``` ```jsx render <Docs.V2WebPropsTable title="V2Header.UtilityBar" propTypeName="V2HeaderUtilityBarProps" /> ``` ```jsx render <Docs.V2WebPropsTable title="V2Header.Actions" propTypeName="V2HeaderActionsProps" /> ``` ```jsx render <Docs.V2WebPropsTable title="V2Header.Navigation" propTypeName="V2HeaderNavigationProps" /> ``` ```jsx render <Docs.V2WebPropsTable title="V2Header.Drawer" propTypeName="V2HeaderDrawerProps" /> ``` ```jsx render <Docs.V2WebPropsTable title="V2Header.DrawerLink" propTypeName="V2HeaderDrawerLinkProps" /> ``` ```jsx render <Docs.V2ClassesTable title="V2Header.Container" classes={[HeaderContainerClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2Header.Brandmark" classes={[HeaderBrandmarkClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2Header.MainContent" classes={[HeaderMainContentClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2Header.UtilityBar" classes={[HeaderUtilityBarClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2Header.Actions" classes={[HeaderActionsClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2Header.Hamburger" classes={[HeaderHamburgerClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2Header.Navigation" classes={[HeaderNavigationClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2Header.Drawer" classes={[HeaderDrawerClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2Header.DrawerLink" classes={[HeaderDrawerLinkClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> ```jsx live () => { const abyssTheme = useAbyssTheme(); const activeBrand = abyssTheme.themeName; const [isOpen, setIsOpen] = useState(false); const matches = useMediaQuery('(min-width: 1520px)'); const menuItems = [ { title: 'Profile', onClick: () => { console.log('Clicked Profile'); }, }, { title: 'Settings', onClick: () => { console.log('Clicked Settings'); }, }, { title: 'Log Out', onClick: () => { console.log('Clicked Log Out'); }, }, ]; const UtilityContent = () => { return ( <React.Fragment> <Heading css={{ padding: '0px $md' }} offset={4} fontWeight="$bold" id="utility-items-title" > About Abyss </Heading> <ul aria-labelledby="utility-items-title" style={{ display: 'flex', flexDirection: 'column', gap: 20 }} > <li> <V2NavMenu.MenuItem title="About Abyss" description="What is Abyss? How does it work? Who are we?" href="https://abyss.uhc.com/web/about/" /> </li> </ul> </React.Fragment> ); }; const UtilityPlans = () => { return ( <React.Fragment> <Heading css={{ padding: '0px $md' }} offset={4} fontWeight="$bold" id="utility-plans-title" > Abyss accessibility </Heading> <ul aria-labelledby="utility-plans-title" style={{ display: 'flex', flexDirection: 'column', gap: 20 }} > <li> <V2NavMenu.MenuItem title="Accessibility" description="We have some information about Abyss accessibility you may want to read." href="https://abyss.uhc.com/web/accessibility/" /> </li> </ul> </React.Fragment> ); }; const UtilityPlanTypes = () => { return ( <React.Fragment> <Heading css={{ padding: '0px $md' }} offset={4} fontWeight="$bold" id="utility-plan-types-title" > WAI-ARIA information </Heading> <ul aria-describedby="utility-plan-types-title" style={{ display: 'flex', flexDirection: 'column', gap: 20, margin: '20px', alignItems: 'center', }} > <li> <V2Link css={{ fontWeight: 'bold', fontSize: '16px' }} href="https://www.w3.org/WAI/ARIA/apg/" > WAI-ARIA Practices Guide 1.1 </V2Link> </li> <li> <V2Link css={{ fontWeight: 'bold', fontSize: '16px' }} href="https://www.w3.org/WAI/ARIA/apg/patterns/" > WAI-ARIA Patterns </V2Link> </li> <li> <V2Link css={{ fontWeight: 'bold', fontSize: '16px' }} href="https://www.w3.org/TR/using-aria/" > The Rules of ARIA (Using ARIA) </V2Link> </li> </ul> </React.Fragment> ); }; const DropdownMenuContent = () => { return ( <V2NavMenu.Columns> <V2NavMenu.Column title="Abyss components"> <V2NavMenu.MenuItem title="Abyss web" href="https://abyss-test.uhc.com/web/overview/" description="Check out the Abyss web components" /> <V2NavMenu.MenuItem title="Abyss mobile" href="https://abyss.uhc.com/mobile/overview/" > Abyss also does mobile native - iOS and Android! </V2NavMenu.MenuItem> </V2NavMenu.Column> <V2NavMenu.Column> <V2NavMenu.MenuItem title="Click events?" onClick={() => console.log('onClick pressed')} description="Yes! Click this to see a message logged to the console." /> </V2NavMenu.Column> <V2NavMenu.Column title="What's your role?"> <V2NavMenu.MenuItem title="Designer?" href="https://abyss.uhc.com/web/designers/design-kit/" description="Check out our design kit" /> <V2NavMenu.MenuItem title="Web developer?" href="https://abyss.uhc.com/web/developers/overview/" description="Start with our devloper overview" /> <V2NavMenu.MenuItem title="Marketing?" href="https://abyss.uhc.com/web/brand/uhc/get-started/" description="We support UHC brands" /> </V2NavMenu.Column> </V2NavMenu.Columns> ); }; const DropdownMenuDrawerContent = () => { return ( <React.Fragment> <Heading css={{ padding: '0px $md' }} offset={4} fontWeight="$bold" id="section-title-1" > Abyss Components </Heading> <ul aria-labelledby="section-title-1" style={{ display: 'flex', flexDirection: 'column', gap: 20 }} > <li> <V2NavMenu.MenuItem title="Abyss web" href="https://abyss-test.uhc.com/web/overview/" description="Check out the Abyss web components" /> </li> <li> <V2NavMenu.MenuItem title="Abyss mobile" href="https://abyss.uhc.com/mobile/overview/" > Abyss also does mobile native - iOS and Android! </V2NavMenu.MenuItem> </li> <li> <V2NavMenu.MenuItem title="Click events?" onClick={() => console.log('onClick pressed')} description="Yes! Click this to see a message logged to the console." /> </li> </ul> <Heading css={{ padding: '0px $md' }} offset={4} fontWeight="$bold" id="section-title-2" > What's your role? </Heading> <ul aria-labelledby="section-title-2" style={{ display: 'flex', flexDirection: 'column', gap: 20 }} > <li> <V2NavMenu.MenuItem title="Designer?" href="https://abyss.uhc.com/web/designers/design-kit/" description="Check out our design kit" /> </li> <li> <V2NavMenu.MenuItem title="Web developer?" href="https://abyss.uhc.com/web/developers/overview/" description="Start with our devloper overview" /> </li> <li> <V2NavMenu.MenuItem title="Marketing?" href="https://abyss.uhc.com/web/brand/uhc/get-started/" description="We support UHC brands" /> </li> </ul> </React.Fragment> ); }; return ( <nav aria-label="Primary"> <nav aria-label="Site info"> <V2Header.UtilityBar> <V2Link href="https://www.uhc.com/about-us">About</V2Link> <V2Link href="/">Help</V2Link> </V2Header.UtilityBar> </nav> <V2Header.Container> <V2Header.Brandmark affiliate={activeBrand} brand={activeBrand} css={{ width: '150px' }} /> <V2Header.Actions> <V2Header.HamburgerMenu onClick={() => { setIsOpen(!isOpen); }} type="button" aria-label="Menu" aria-haspopup="dialog" > <IconSymbol icon={isOpen ? 'close' : 'menu'} /> </V2Header.HamburgerMenu> </V2Header.Actions> {matches && ( <Layout.Group space={20}> <V2NavMenu.Root variant="inverted" zIndex={202} hasOverlay> <V2NavMenu.List> <V2NavMenu.Item> <V2NavMenu.Trigger variant="inverted"> Accessibility </V2NavMenu.Trigger> <V2NavMenu.Content> <V2NavMenu.Columns> <V2NavMenu.Column> <V2NavMenu.MenuItem title="Accessibility" href="https://abyss.uhc.com/web/accessibility/" > Abyss accessibility information </V2NavMenu.MenuItem> <V2NavMenu.MenuItem title="WAI-ARIA Patterns" href="https://www.w3.org/WAI/ARIA/apg/patterns/" > Many of our components are based upon these patterns </V2NavMenu.MenuItem> </V2NavMenu.Column> </V2NavMenu.Columns> </V2NavMenu.Content> </V2NavMenu.Item> <V2NavMenu.Link variant="inverted" href="https://uhgazure.sharepoint.com/sites/accessibility-knowledge-center/" > ACOE Resources </V2NavMenu.Link> </V2NavMenu.List> </V2NavMenu.Root> </Layout.Group> )} </V2Header.Container> <V2Header.Container> <V2Header.Brandmark css={{ margin: '-10px 0px 0px 60px', height: '35px', width: '250px', }} logo={ <> <IconBrand icon="government" size={32} /> <Text> Government</Text> </> } /> </V2Header.Container> <V2Header.Navigation menuActive={isOpen}> <nav aria-label="Site"> <V2NavMenu.Root hasOverlay> <V2NavMenu.List> <V2NavMenu.Link href="#">Home</V2NavMenu.Link> <V2NavMenu.Item> <V2NavMenu.Trigger>Components</V2NavMenu.Trigger> <V2NavMenu.Content> <DropdownMenuContent /> </V2NavMenu.Content> </V2NavMenu.Item> </V2NavMenu.List> </V2NavMenu.Root> </nav> </V2Header.Navigation> </nav> ); }; ``` ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Tab', description: 'Moves focus to the next focusable element', }, { name: 'Enter', description: 'If the logo is selected, redirects to the specified link. If focus is inside the navigation menu, redirects to the link if the menu bar item is a redirect, or opens the relevant dropdown menu if the item has one', }, { name: 'Space', description: 'If focus on a menu bar item with a dropdown, opens the relevant dropdown menu', }, { name: 'Left Arrow', description: 'When focus is inside one of the navigation menus, focuses the previous menu bar item', }, { name: 'Up Arrow', description: 'When focus is inside one of the navigation menus, focuses the previous menu bar item', }, { name: 'Right Arrow', description: 'When focus is inside one of the navigation menus, focuses the next menu bar item', }, { name: 'Down Arrow', description: 'When focus is inside one of the navigation menus, focuses the next menu bar item. If focus is on an open menu bar item, moves focus into its dropdown menu', }, { name: 'Escape', description: 'Closes open dropdown menu and moves focus to its menu bar item', }, { name: 'Home', description: 'If inside a navigation menu, moves focus to the first item in the menu', }, { name: 'End', description: 'If inside a navigation menu, moves focus to the last item in the menu', }, ]} /> ``` </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={'V2Header'} keys={['headerV2']} /> ``` </Tab> --- id: heading category: Typography title: Heading description: Creates appropriately sized and nested heading elements. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=3-16201 --- <Tab label="Overview"> ```jsx import { Heading } from '@uhg-abyss/web/ui/Heading'; ``` ```jsx sandbox { component: 'Heading', inputs: [ { prop: 'children', type: 'string', defaultValue: 'Heading', }, { prop: 'offset', type: 'select', options: [ { label: '0', value: '0' }, { label: '1', value: '1' }, { label: '2', value: '2' }, { label: '3', value: '3' }, { label: '4', value: '4' }, { label: '5', value: '5' }, ], }, { prop: 'color', type: 'select', options: [ { label: '$primary1', value: '$primary1' }, { label: '$interactive1', value: '$interactive1' }, { label: '$gray8', value: '$gray8' }, { label: 'lightseagreen', value: 'lightseagreen' }, { label: '#ff0000', value: '#ff0000' }, ], }, { prop: 'textAlign', type: 'select', options: [ { label: 'left', value: 'left' }, { label: 'center', value: 'center' }, { label: 'right', value: 'right' }, ], }, ] } <Heading>Heading</Heading> ``` ## Usage If we want to add a new h2 to the page and lower every other heading it's now easy to add another `<Heading.Level>` wrapper to indent everything and you're done. Much easier than updating lots of `<h>` numbers around the code to realign them all. The `<Heading.Level>` concept means you only need to think about whether it's a deeper level, without having to know the specific heading level number. ```jsx live <React.Fragment> <Heading>This is h1 title</Heading> <Heading.Level> <Heading>This is h2 title</Heading> </Heading.Level> </React.Fragment> ``` ## Offset If you want to have heading levels relative to the current level you can provide an offset prop, which is a more concise way of writing `<Heading.Level>` at each heading breakpoint. This will override the heading level, and allow you to manually set the level corresponding to the design. However `<Level>` will establish a new deeper heading level context whereas offset will not, again, requiring you to manually set the offet level with each new heading. You can use `offset={0|1|2|3|4|5}`. The below headings are `h1` followed by an `h5`. ```jsx live <React.Fragment> <Heading>Providers</Heading> <Heading offset={4}>Choose your primary provider</Heading> <p> Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. </p> </React.Fragment> ``` ## Display The `display` prop has two different usages based on styling needs. Use numbers to target one of three display sizes: `1 | 2 | 3`. Display sizes are `<h1>` tags, with options that are the largest sizes in the DPL. Use heading level styles as a string: `'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'`. ```jsx live <React.Fragment> <Heading display={2}>Welcome to UnitedHealth</Heading> <Heading display={3}>Welcome to UnitedHealth</Heading> <Heading display="h2">Welcome to UnitedHealth</Heading> <Heading display="h3">Welcome to UnitedHealth</Heading> </React.Fragment> ``` ## Nesting Nesting headers, allows us to have multiple levels of headers, without having to directly tag each level of `<h>` tags. Each level of heading is specifically designed to take up the same height of space, given a specific `font-size` and `margin`. ```jsx live <React.Fragment> <Heading>This is h1 title</Heading> <Heading.Level> <Heading>This is h2 title</Heading> <Heading.Level> <Heading>This is h3 title</Heading> <Heading.Level> <Heading>This is h4 title</Heading> <Heading.Level> <Heading>This is h5 title</Heading> <Heading.Level> <Heading>This is h6 title</Heading> </Heading.Level> </Heading.Level> </Heading.Level> </Heading.Level> </Heading.Level> </React.Fragment> ``` ## Nesting example Nested headers can be combined together with text to organize sections and create a seamless document experience. ```jsx live <React.Fragment> <Heading>Medical Visit</Heading> <Heading.Level> <Heading>Planned Visits</Heading> <Heading.Level> <Heading color="$interactive1">Clinical Care</Heading> <p> Vitae nunc sed velit dignissim. Nunc congue nisi vitae suscipit tellus mauris a diam. Risus in hendrerit gravida rutrum quisque non tellus. Orci nulla pellentesque dignissim enim sit. </p> <Heading color="$interactive1">Professional Care</Heading> <p> Porttitor leo a diam sollicitudin tempor id eu nisl. Donec ultrices tincidunt arcu non sodales neque sodales. Et malesuada fames ac turpis egestas integer eget. Pretium vulputate sapien nec sagittis. Lobortis scelerisque fermentum dui faucibus. </p> </Heading.Level> <Heading>Emergency Visits</Heading> <Heading.Level> <Heading color="$interactive1">Emergency Room Care</Heading> <p> Nunc faucibus a pellentesque sit. In ante metus dictum at tempor commodo ullamcorper a. Ut sem nulla pharetra diam sit amet nisl suscipit adipiscing. Urna et pharetra pharetra massa massa. Velit sed ullamcorper morbi tincidunt ornare massa eget. Orci nulla pellentesque dignissim enim. Scelerisque fermentum dui faucibus in. Duis at tellus at urna condimentum mattis pellentesque id. </p> </Heading.Level> </Heading.Level> </React.Fragment> ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={Heading} rows={[ { name: 'animated', type: 'boolean', description: 'Flag to make component animatable', }, { name: 'offset', type: 'number', description: '0 | 1 | 2 | 3 | 4 | 5. Each number will offset the hierarchy of heading you choose. 0 is <h1>, and so on', }, { name: 'children', type: 'string', description: 'The text to be input into the heading component', }, { name: 'textAlign', type: 'start | center', description: '', }, { name: 'color', type: 'string', description: 'Set the color of the heading text', }, { name: 'display', type: 'number or string', description: 'Target one of three display sizes by passing in a number. Target styling for a heading level by passing in a string', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Heading} rows={[ { name: 'heading-root', description: 'Heading root element', }, ]} /> ``` </Tab> --- id: i18n-provider category: Providers title: I18nProvider description: Used to provide i18n data to the application. sourceIsTS: true --- <Tab label="Overview"> ```jsx import { I18nProvider } from '@uhg-abyss/web/ui/I18nProvider'; ``` ## Usage Abyss supports overriding the default i18n object by using the `I18nProvider` component. `I18nProvider` accepts a single prop, `translations`, which is an object containing the translation overrides. The translations object for overrides will be in the following format: ```jsx { [commonWord]: 'Translated Value', [componentName]: { [key]: 'Translated Value', }, } ``` The `commonWord` key is used to override the default translations for common words used in Abyss components. The `componentName` key with an object value is for strings within specific Abyss components that allow an additional scope to other keys. Below is an example of a few of the strings in our default i18n object: ```jsx { openInNewWindow: 'opens in a new window', save: 'Save', search: 'Search', DataTable: { downloadDropdown: { filtered: 'Download filtered dataset (CSV)', full: 'Download full dataset (CSV)', label: 'Download', }, }, NumberInput: { aria: { decrementButton: { label: 'decrement by {{stepValue}}', }, incrementButton: { label: 'increment by {{stepValue}}', }, }, }, } ``` When using the `t` function from the [useTranslate](/web/hooks/use-translate) hook or the [Translate](/web/ui/translate) component, the key will be in dotted notation. For example, the key `'DataTable.downloadDropdown.label'` will be used to get the value `'Download'` from the i18n object. Our [default i18n object](https://github.com/uhc-tech/abyss/blob/main/packages/abyss-web/src/tools/i18n/translations/en.ts) contains all strings used in Abyss components. ## Example Let's use the [ResultCount](/web/ui/pagination#resultcount) component as an example. This component displays the currently visible results and the total number of results. ```jsx live () => { return ( <Layout.Stack alignItems="left"> <Text fontWeight="bold">Multiple Results</Text> <ResultCount pageIndex={0} pageSize={5} resultsTotalCount={10} /> <Text fontWeight="bold">Single Result</Text> <ResultCount pageIndex={0} pageSize={5} resultsTotalCount={1} /> <Text fontWeight="bold">No Results</Text> <ResultCount pageIndex={0} pageSize={5} resultsTotalCount={0} /> </Layout.Stack> ); }; ``` Internally, we use the following keys to read the values from our i18n object: - `ResultCount.multipleResults` - `ResultCount.singleResult` - `ResultCount.noResults` These values can be overridden with the `translations` prop in the `I18nProvider` component. Let's change the values so that the component mentions "records" instead of "results". ```jsx live () => { return ( <I18nProvider translations={{ ResultCount: { multipleResults: 'Showing {{resultFrom}}-{{resultTo}} of {{resultsTotalCount}} records', singleResult: 'Record {{resultFrom}} of {{resultsTotalCount}}', noResults: 'No records found', }, }} > <Layout.Stack alignItems="left"> <Text fontWeight="bold">Multiple Results</Text> <ResultCount pageIndex={0} pageSize={5} resultsTotalCount={10} /> <Text fontWeight="bold">Single Result</Text> <ResultCount pageIndex={0} pageSize={5} resultsTotalCount={1} /> <Text fontWeight="bold">No Results</Text> <ResultCount pageIndex={0} pageSize={5} resultsTotalCount={0} /> </Layout.Stack> </I18nProvider> ); }; ``` ## Language translations We can use the same idea to translate text into different languages (German, in this case). ```jsx live () => { return ( <I18nProvider translations={{ ResultCount: { multipleResults: '{{resultFrom}}-{{resultTo}} von {{resultsTotalCount}} Ergebnissen angezeigt', singleResult: 'Ergebnis {{resultFrom}} von {{resultsTotalCount}}', noResults: 'Keine Ergebnisse gefunden', }, }} > <Layout.Stack alignItems="left"> <Text fontWeight="bold">Multiple Results</Text> <ResultCount pageIndex={0} pageSize={5} resultsTotalCount={10} /> <Text fontWeight="bold">Single Result</Text> <ResultCount pageIndex={0} pageSize={5} resultsTotalCount={1} /> <Text fontWeight="bold">No Results</Text> <ResultCount pageIndex={0} pageSize={5} resultsTotalCount={0} /> </Layout.Stack> </I18nProvider> ); }; ``` ## Custom i18n Besides overriding the default values used in Abyss components, the `I18nProvider` can also be used to provide custom text values. These values can then be consumed later using the [useTranslate](/web/hooks/use-translate) hook or the [Translate](/web/ui/translate) component in the same manner as before. ```jsx live const UseTranslateComponent = () => { const { t } = useTranslate(); return ( <Layout.Stack alignItems="left"> <Text>{t('myCustomText', { method: 'useTranslate hook' })}</Text> <Text>{t('nested.key')}</Text> </Layout.Stack> ); }; const TranslateComponent = () => { return ( <Translate> {({ t }) => { return ( <Layout.Stack alignItems="left"> <Text>{t('myCustomText', { method: 'Translate component' })}</Text> <Text>{t('nested.key')}</Text> </Layout.Stack> ); }} </Translate> ); }; render(() => { return ( <I18nProvider translations={{ myCustomText: 'My custom text ({{method}})', nested: { key: 'Nested Value' }, }} > <UseTranslateComponent /> <TranslateComponent /> </I18nProvider> ); }); ``` ## Related links - [useTranslate](/web/hooks/use-translate) - [Translate](/web/ui/translate) </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={I18nProvider} rows={[ { name: 'children', type: 'React.ReactNode', description: 'The rest of the component tree', }, { name: 'translations', type: 'object', description: 'The translations to override the default translations with', }, ]} /> ``` </Tab> --- id: icon category: Media title: Icon description: Used to implement icons and adapt their properties. sourceIsTS: true --- <Tab label="Overview"> ```jsx import { Icon } from '@uhg-abyss/web/ui/Icon'; ``` ```jsx sandbox { component: 'Icon', inputs: [ { prop: 'size', type: 'string', }, { prop: 'title', type: 'string', }, { prop: 'color', type: 'string', }, { prop: 'isScreenReadable', type: 'boolean', }, ] } () => { const customIcon = ( <svg height="24" width="24" viewBox="0 0 16 16"> <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z" /> </svg> ); return ( <Icon size="24px" title="github">{customIcon}</Icon> ); }; ``` ## Usage Use `Icon` to implement custom SVG icons ```jsx live <Layout.Group> <Icon title="github" size="$md"> <svg height="24" width="24" viewBox="0 0 16 16"> <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z" /> </svg> </Icon> <Icon title="figma" size="$md"> <svg viewBox="-60 0 500 500"> <path d="M14 95.7924C14 42.8877 56.8878 0 109.793 0H274.161C327.066 0 369.954 42.8877 369.954 95.7924C369.954 129.292 352.758 158.776 326.711 175.897C352.758 193.019 369.954 222.502 369.954 256.002C369.954 308.907 327.066 351.795 274.161 351.795H272.081C247.279 351.795 224.678 342.369 207.666 326.904V415.167C207.666 468.777 163.657 512 110.309 512C57.5361 512 14 469.243 14 416.207C14 382.709 31.1945 353.227 57.2392 336.105C31.1945 318.983 14 289.5 14 256.002C14 222.502 31.196 193.019 57.2425 175.897C31.196 158.776 14 129.292 14 95.7924ZM176.288 191.587H109.793C74.2172 191.587 45.3778 220.427 45.3778 256.002C45.3778 291.44 73.9948 320.194 109.381 320.416C109.518 320.415 109.655 320.415 109.793 320.415H176.288V191.587ZM207.666 256.002C207.666 291.577 236.505 320.417 272.081 320.417H274.161C309.737 320.417 338.576 291.577 338.576 256.002C338.576 220.427 309.737 191.587 274.161 191.587H272.081C236.505 191.587 207.666 220.427 207.666 256.002ZM109.793 351.795C109.655 351.795 109.518 351.794 109.381 351.794C73.9948 352.015 45.3778 380.769 45.3778 416.207C45.3778 451.652 74.6025 480.622 110.309 480.622C146.591 480.622 176.288 451.186 176.288 415.167V351.795H109.793ZM109.793 31.3778C74.2172 31.3778 45.3778 60.2173 45.3778 95.7924C45.3778 131.368 74.2172 160.207 109.793 160.207H176.288V31.3778H109.793ZM207.666 160.207H274.161C309.737 160.207 338.576 131.368 338.576 95.7924C338.576 60.2173 309.737 31.3778 274.161 31.3778H207.666V160.207Z" /> </svg> </Icon> </Layout.Group> ``` ## Colors Use the `color` property to adjust the color of a Google material icon. Theme colors can be found in the <BrandLink category="colors">Colors</BrandLink> documentation section or a hex code can be used. The default color is set to the theme `'interactive1'`. ```jsx live <Layout.Group> <Icon title="github" size="$md" color="$primary1"> <svg height="24" width="24" viewBox="0 0 16 16"> <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z" /> </svg> </Icon> <Icon title="github" size="$md" color="#00ff00"> <svg height="24" width="24" viewBox="0 0 16 16"> <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z" /> </svg> </Icon> </Layout.Group> ``` ## Size Use the `size` property to adjust the size of an icon by setting it to a specific preset size or number. The default is set to `24px` || `$md`. The size prop can take in px, and the Abyss standardized $sm, $md, and $lg. ```jsx live () => { const customIcon = ( <svg height="24" width="24" viewBox="0 0 16 16"> <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z" /> </svg> ); return ( <Layout.Group> <Icon title="github">{customIcon}</Icon> <Icon title="github" size="$md"> {customIcon} </Icon> <Icon title="github" size={24}> {customIcon} </Icon> </Layout.Group> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="Icon" propTypeName="IconProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2ClassesTable title="Icon" classes={[IconClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> <h2>Meaningful or Control Icons</h2> If the icon is being used in a setting where it is the only element providing meaning, then that same meaning should be conveyed to screen reader users. The below implementation provides examples of situations in which the property `isScreenReadable` should be set to true and the `title` property is required and should describe the purpose of the image. Example 1: An alert icon is used to convey a sense of urgency; there is adjacent text (“There is a data outage”) but the text doesn't include any words that convey urgency. So, in this case, the icon should have a text alternative such as “Alert” or “Warning”. ```jsx live <Layout.Group> <IconBrand title="alert" icon="alert" isScreenReadable={true} size={24} /> <div>There is a data outage</div> </Layout.Group> ``` <br /> Example 2: An “X” material icon is used as a close button on a modal dialog. There is no adjacent text, so the icon should have a text alternative of “close” or “close window”. ```jsx live <Layout.Group> <IconSymbol title="close" icon="close" isScreenReadable={true} size={24} /> </Layout.Group> ``` <h2>Decorative Icons</h2> If the icon is being used in a setting in which it just a decorative element (which is the default case for icons), then the icon should be ignored by screen readers. The below implementation provides example of which situations would be classified as decorative. Since the default of `isScreenReadable` is set to false no specific changes need to be made for decorative icons. Example 1: An alert icon is used next to an urgent message and the word “Alert” is included in the adjacent text. In this case, the icon becomes decorative in nature and should be ignored by screen readers. ```jsx live <Layout.Group> <IconBrand icon="alert" size={24} /> <div>Alert: There is a data outage</div> </Layout.Group> ``` <br /> Example 2: An “X” material icon is used as a close button on a modal dialog; the word “Close” appears to the right of the button. In this case, the icon should be considered decorative and ignored by screen readers. ```jsx live <Layout.Group> <IconSymbol icon="close" size={24} /> <div>Close</div> </Layout.Group> ``` <h2>Icon, IconBrand, and IconSymbol examples</h2> Samples of all three icon components with and without titles (alt text): ```jsx live <Layout.Stack space={20} alignItems="left"> <Heading offset={4}>Decorative: No title</Heading> <Text>Icons that duplicate or reinforce text content</Text> <Layout.Group space={40}> <> <Icon size="$md"> <svg height="24" width="24" viewBox="0 0 16 16"> <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z" /> </svg> </Icon> <Text css={{ paddingLeft: 5 }}>Github source</Text> </> <> <IconBrand icon="alert" size={24} /> <Text css={{ paddingLeft: 5 }}> <b>Alert: Issues found!</b> </Text> </> <> <IconSymbol icon="close" size={24} /> <Text css={{ paddingLeft: 5 }}>Close window</Text> </> </Layout.Group> <Heading offset={4} css={{ marginTop: 30 }}> Icon-only: Require title (alt text) </Heading> <Text> Icons conveying information that is not part of the text (if any). </Text> <Layout.Group space={40}> <> <Icon size="$md" title="Github"> <svg height="24" width="24" viewBox="0 0 16 16"> <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z" /> </svg> </Icon> <Text css={{ paddingLeft: 5 }}>Source</Text> </> <> <IconBrand icon="alert" size={24} title="Alert" /> <Text css={{ paddingLeft: 5 }}> <b>Issues found!</b> </Text> </> <IconSymbol icon="close" size={24} title="Close window" /> </Layout.Group> </Layout.Stack> ``` </Tab> --- id: icon-material category: Media title: IconMaterial description: Used to implement material icons and adapt their properties. design: https://www.figma.com/design/anZoHg026SyKJHWGJ7Vf4Q/Abyss-Icons?node-id=1-432 --- <Tab label="Overview"> ```jsx import { IconMaterial } from '@uhg-abyss/web/ui/IconMaterial'; ``` ```jsx render <Docs.V2Deprecated componentName="IconMaterial"> <V2Text color="$web.semantic.color.text.content.tertiary"> Please migrate your component over to{' '} <V2Link href="/web/ui/icon-symbol">IconSymbol</V2Link>. </V2Text> </Docs.V2Deprecated> ``` <br></br> ```jsx sandbox { component: 'IconMaterial', inputs: [ { prop: 'icon', type: 'string', }, { prop: 'color', type: 'string', }, { prop: 'size', type: 'string', }, { prop: 'variant', type: 'select', options: [ { label: 'filled', value: 'filled' }, { label: 'outlined', value: 'outlined' }, ], }, ] } <IconMaterial icon="home" size="24px" variant="filled" color="$interactive1" /> ``` ## Icons Use the `icon` property to adjust which icon is being selected. Note: When using TypeScript, the `icon` property only accepts valid icon names. If an invalid icon name is provided, an error will be thrown. To verify that a given value is a valid icon name, use the [isValidAssetName tool](/web/tools/is-valid-asset-name) or use the `ValidIconMaterialName` type: ```ts import { ValidIconMaterialName } from '@uhg-abyss/web/ui/IconMaterial'; let iconName: ValidIconMaterialName; ``` ```jsx live <Layout.Group> <IconMaterial icon="bookmarks" size={24} /> <IconMaterial icon="face" size={24} /> <IconMaterial icon="home" size={24} /> </Layout.Group> ``` ## Colors Use the `color` property to adjust the color of a Google material icon. Theme colors can be found in the <BrandLink category="colors">Colors</BrandLink> documentation section or a hex code can be used. The default color is set to the theme `'interactive1'`. ```jsx live <Layout.Group> <IconMaterial icon="home" size={24} /> <IconMaterial icon="home" size={24} color="$success1" /> <IconMaterial icon="home" size={24} color="$error1" /> <IconMaterial icon="home" size={24} color="$primary1" /> <IconMaterial icon="home" size={24} color="#00ff00" /> <IconMaterial icon="home" size={24} color="violet" /> </Layout.Group> ``` ## Size Use the `size` property to adjust the size of an icon by setting it to a specific number. The default size is set to 24. ```jsx live <Layout.Group> <IconMaterial icon="home" size={16} /> <IconMaterial icon="home" size={20} /> <IconMaterial icon="home" /> </Layout.Group> ``` ## Material icon variants Use the `variant` property to change the style of Material icons. The default variant is `filled`. ```jsx live <Grid columns={5} span={{ md: '50%', lg: '20%' }}> <Grid.Col> <Box padding="$sm" color="$white"> <Layout.Stack grow space={0}> <div style={{ lineHeight: 2 }}>filled</div> <div style={{ lineHeight: 2 }}>outlined</div> </Layout.Stack> </Box> </Grid.Col> <Grid.Col> <Box padding="$sm" color="$white"> <Layout.Stack grow space={2}> <IconMaterial icon="health_and_safety" size={24} variant="filled" /> <IconMaterial icon="health_and_safety" size={24} variant="outlined" /> </Layout.Stack> </Box> </Grid.Col> <Grid.Col> <Box padding="$sm" color="$tint3"> <Layout.Stack grow space={2}> <IconMaterial icon="health_and_safety" size={24} variant="filled" /> <IconMaterial icon="health_and_safety" size={24} variant="outlined" /> </Layout.Stack> </Box> </Grid.Col> <Grid.Col> <Box padding="$sm" color="$tint4"> <Layout.Stack grow space={2}> <IconMaterial icon="health_and_safety" size={24} variant="filled" /> <IconMaterial icon="health_and_safety" size={24} variant="outlined" /> </Layout.Stack> </Box> </Grid.Col> <Grid.Col> <Box padding="$sm" color="$primary1"> <Layout.Stack grow space={2}> <IconMaterial icon="health_and_safety" size={24} variant="filled" color="white" /> <IconMaterial icon="health_and_safety" size={24} variant="outlined" color="white" /> </Layout.Stack> </Box> </Grid.Col> </Grid> ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={Icon} rows={[ { name: 'title', type: 'string', description: 'Set the title of the icon', }, { name: 'children', type: 'ReactNode', description: 'The svg content of the icon', }, { name: 'color', type: 'string', description: 'Set the color of the icon', }, { name: 'size', type: 'number | string', description: 'Set the size of the icon', }, { name: 'isScreenReadable', type: 'boolean', description: 'Indicate whether the icon is screen readable or not. If the icon is Screen Readable, then provide a title', }, { name: 'sizes', type: 'shape', description: '(not currently functioning) Pre programmed sizes for the icons', }, ]} /> ``` ```jsx render <Docs.PropsTable of={IconMaterial} rows={[ { name: 'icon', type: 'string', description: 'Name of the material icon', }, { name: 'variant', type: 'filled | outlined', description: 'The style variation of the material icon.', }, { name: 'color', type: 'string', description: 'Set the color of the material icon', }, { name: 'size', type: 'number | string', description: 'Set the size of the material icon', }, { name: 'title', type: 'string', description: 'Set the title of the material icon', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Icon} rows={[ { name: 'icon-root', description: 'Icon root element', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={IconMaterial} rows={[ { name: 'icon-material-root', description: 'Icon Material root element', }, ]} /> ``` </Tab> <Tab label="Accessibility"> <h2>Meaningful or Control Icons</h2> If the icon is being used in a setting where it is the only element providing meaning, then that same meaning should be conveyed to screen reader users. The below implementation provides examples of situations in which the property `isScreenReadable` should be set to true and the `title` property is required and should describe the purpose of the image. Example 1: An alert icon is used to convey a sense of urgency; there is adjacent text (“There is a data outage”) but the text doesn't include any words that convey urgency. So, in this case, the icon should have a text alternative such as “Alert” or “Warning”. ```jsx live <Layout.Group> <IconBrand title="alert" icon="alert" isScreenReadable={true} size={24} /> <div>There is a data outage</div> </Layout.Group> ``` Example 2: An “X” material icon is used as a close button on a modal dialog. There is no adjacent text, so the icon should have a text alternative of “close” or “close window”. ```jsx live <Layout.Group> <IconMaterial title="close" icon="close" isScreenReadable={true} size={24} /> </Layout.Group> ``` <h2>Decorative Icons</h2> If the icon is being used in a setting in which it just a decorative element (which is the default case for icons), then the icon should be ignored by screen readers. The below implementation provides example of which situations would be classified as decorative. Since the default of `isScreenReadable` is set to false no specific changes need to be made for decorative icons. Example 1: An alert icon is used next to an urgent message and the word “Alert” is included in the adjacent text. In this case, the icon becomes decorative in nature and should be ignored by screen readers. ```jsx live <Layout.Group> <IconBrand icon="alert" size={24} /> <div>Alert: There is a data outage</div> </Layout.Group> ``` Example 2: An “X” material icon is used as a close button on a modal dialog; the word “Close” appears to the right of the button. In this case, the icon should be considered decorative and ignored by screen readers. ```jsx live <Layout.Group> <IconMaterial icon="close" size={24} /> <div>Close</div> </Layout.Group> ``` </Tab> <Tab label="Material Icons"> ```jsx render <h2>Material Icons</h2> ``` Abyss uses Google's Material Design System iconography that is simple, modern, friendly, and sometimes quirky. Each icon is created using Google's design guidelines to depict in simple and minimal forms the universal concepts used commonly throughout user interfaces. Ensuring readability and clarity at both large and small sizes, these icons have been optimized for common platforms and display resolutions. The source for these design icons can be found in the <ExitLink href="https://fonts.google.com/icons)">Material Icons Library</ExitLink>. <IconLibrary brand="material" noDownload /> </Tab> --- id: icon-symbol category: Media title: IconSymbol description: Used to implement Material Symbol icons and adapt their properties. sourceIsTS: true --- <Tab label="Overview"> ```jsx import { IconSymbol } from '@uhg-abyss/web/ui/IconSymbol'; ``` ```jsx sandbox { component: 'IconSymbol', inputs: [ { prop: 'icon', type: 'string', }, { prop: 'color', type: 'string', }, { prop: 'size', type: 'string', }, { prop: 'variant', type: 'select', options: [ { label: 'filled', value: 'filled' }, { label: 'outlined', value: 'outlined' }, ], }, ] } <IconSymbol icon="home" size="24px" variant="filled" color="$interactive1" /> ``` ## Icons Use the `icon` property to adjust which icon is being selected. Note: When using TypeScript, the `icon` property only accepts valid icon names. If an invalid icon name is provided, an error will be thrown. To verify that a given value is a valid icon name, use the [isValidAssetName tool](/web/tools/is-valid-asset-name) or use the `ValidIconSymbolName` type: ```ts import { ValidIconSymbolName } from '@uhg-abyss/web/ui/IconSymbol'; let iconName: ValidIconSymbolName; ``` ```jsx live <Layout.Group> <IconSymbol icon="bookmarks" size={24} /> <IconSymbol icon="face" size={24} /> <IconSymbol icon="home" size={24} /> </Layout.Group> ``` ## Colors Use the `color` property to adjust the color of a Symbol icon. Theme colors can be found in the <BrandLink category="colors">Colors</BrandLink> documentation section or a hex code can be used. The default color is set to the theme `'interactive1'`. ```jsx live <Layout.Group> <IconSymbol icon="home" size={24} /> <IconSymbol icon="home" size={24} color="$success1" /> <IconSymbol icon="home" size={24} color="$error1" /> <IconSymbol icon="home" size={24} color="$primary1" /> <IconSymbol icon="home" size={24} color="#00ff00" /> <IconSymbol icon="home" size={24} color="violet" /> </Layout.Group> ``` ## Size Use the `size` property to adjust the size of an icon by setting it to a specific number. The default size is set to 24. ```jsx live <Layout.Group> <IconSymbol icon="home" size={16} /> <IconSymbol icon="home" size={20} /> <IconSymbol icon="home" /> </Layout.Group> ``` ## Symbol icon variants Use the `variant` property to change the style of Symbol icons. The default variant is `filled`. ```jsx live <Grid columns={5} span={{ md: '50%', lg: '20%' }}> <Grid.Col> <Box padding="$sm" color="$white"> <Layout.Stack grow space={0}> <div style={{ lineHeight: 2 }}>filled</div> <div style={{ lineHeight: 2 }}>outlined</div> </Layout.Stack> </Box> </Grid.Col> <Grid.Col> <Box padding="$sm" color="$white"> <Layout.Stack grow space={2}> <IconSymbol icon="health_and_safety" size={24} variant="filled" /> <IconSymbol icon="health_and_safety" size={24} variant="outlined" /> </Layout.Stack> </Box> </Grid.Col> <Grid.Col> <Box padding="$sm" color="$tint3"> <Layout.Stack grow space={2}> <IconSymbol icon="health_and_safety" size={24} variant="filled" /> <IconSymbol icon="health_and_safety" size={24} variant="outlined" /> </Layout.Stack> </Box> </Grid.Col> <Grid.Col> <Box padding="$sm" color="$tint4"> <Layout.Stack grow space={2}> <IconSymbol icon="health_and_safety" size={24} variant="filled" /> <IconSymbol icon="health_and_safety" size={24} variant="outlined" /> </Layout.Stack> </Box> </Grid.Col> <Grid.Col> <Box padding="$sm" color="$primary1"> <Layout.Stack grow space={2}> <IconSymbol icon="health_and_safety" size={24} variant="filled" color="white" /> <IconSymbol icon="health_and_safety" size={24} variant="outlined" color="white" /> </Layout.Stack> </Box> </Grid.Col> </Grid> ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="IconSymbol" propTypeName="IconSymbolProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2ClassesTable title="IconSymbol" classes={[IconSymbolClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> <h2>Meaningful or Control Icons</h2> If the icon is being used in a setting where it is the only element providing meaning, then that same meaning should be conveyed to screen reader users. The below implementation provides examples of situations in which the property `isScreenReadable` should be set to true and the `title` property is required and should describe the purpose of the image. Example 1: An alert icon is used to convey a sense of urgency; there is adjacent text (“There is a data outage”) but the text doesn't include any words that convey urgency. So, in this case, the icon should have a text alternative such as “Alert” or “Warning”. ```jsx live <Layout.Group> <IconBrand title="alert" icon="alert" isScreenReadable={true} size={24} /> <div>There is a data outage</div> </Layout.Group> ``` Example 2: An “X” symbol icon is used as a close button on a modal dialog. There is no adjacent text, so the icon should have a text alternative of “close” or “close window”. ```jsx live <Layout.Group> <IconSymbol title="close" icon="close" isScreenReadable={true} size={24} /> </Layout.Group> ``` <h2>Decorative Icons</h2> If the icon is being used in a setting in which it just a decorative element (which is the default case for icons), then the icon should be ignored by screen readers. The below implementation provides example of which situations would be classified as decorative. Since the default of `isScreenReadable` is set to false no specific changes need to be made for decorative icons. Example 1: An alert icon is used next to an urgent message and the word “Alert” is included in the adjacent text. In this case, the icon becomes decorative in nature and should be ignored by screen readers. ```jsx live <Layout.Group> <IconBrand icon="alert" size={24} /> <div>Alert: There is a data outage</div> </Layout.Group> ``` Example 2: An “X” symbol icon is used as a close button on a modal dialog; the word “Close” appears to the right of the button. In this case, the icon should be considered decorative and ignored by screen readers. ```jsx live <Layout.Group> <IconSymbol icon="close" size={24} /> <div>Close</div> </Layout.Group> ``` <h2>Icon, IconBrand, and IconSymbol examples</h2> Samples of all three icon components with and without titles (alt text): ```jsx live <Layout.Stack space={20} alignItems="left"> <Heading offset={4}>Decorative: No title</Heading> <Text>Icons that duplicate or reinforce text content</Text> <Layout.Group space={40}> <> <Icon size="$md"> <svg height="24" width="24" viewBox="0 0 16 16"> <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z" /> </svg> </Icon> <Text css={{ paddingLeft: 5 }}>Github source</Text> </> <> <IconBrand icon="alert" size={24} /> <Text css={{ paddingLeft: 5 }}> <b>Alert: Issues found!</b> </Text> </> <> <IconSymbol icon="close" size={24} /> <Text css={{ paddingLeft: 5 }}>Close window</Text> </> </Layout.Group> <Heading offset={4} css={{ marginTop: 30 }}> Icon-only: Require title (alt text) </Heading> <Text> Icons conveying information that is not part of the text (if any). </Text> <Layout.Group space={40}> <> <Icon size="$md" title="Github"> <svg height="24" width="24" viewBox="0 0 16 16"> <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z" /> </svg> </Icon> <Text css={{ paddingLeft: 5 }}>Source</Text> </> <> <IconBrand icon="alert" size={24} title="Alert" /> <Text css={{ paddingLeft: 5 }}> <b>Issues found!</b> </Text> </> <IconSymbol icon="close" size={24} title="Close window" /> </Layout.Group> </Layout.Stack> ``` </Tab> <Tab label="Symbol Icons"> ```jsx render <h2>Symbol Icons</h2> ``` Abyss uses Google's Symbol Design System iconography that is simple, modern, friendly, and sometimes quirky. Each icon is created using Google's design guidelines to depict in simple and minimal forms the universal concepts used commonly throughout user interfaces. Ensuring readability and clarity at both large and small sizes, these icons have been optimized for common platforms and display resolutions. The source for these design icons can be found in the <ExitLink href="https://fonts.google.com/icons)">Material Symbol Icons Library</ExitLink>. <IconLibrary brand="symbolWeb" noDownload /> </Tab> --- id: indicator-v2 category: Data Display title: V2Indicator description: Adds an indicator to wrapped elements. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=10966-32 subDirectory: Indicator/v2 sourceIsTS: true --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="Indicator"></Docs.V2MigrationBanner> ``` ```jsx import { V2Indicator } from '@uhg-abyss/web/ui/Indicator'; ``` ## Usage To apply, wrap the `V2Indicator` component around an existing element. By default the Indicator will be positioned in the top-right corner of the child element. Please note that there are accessibility concerns when utilizing this component and further information can be found on the Accessibility tab of this page as well as below in the [Indicator type](#indicator-type) / [Focusable element](#focusable-element) sections. For further details on implementation, please see the various sections below. ```jsx sandbox { component: 'V2Indicator', inputs: [ { prop: 'label', type: 'string', }, { prop: 'offset', type: 'number', }, { prop: 'overflowCount', type: 'number', }, { prop: 'position', type: 'select', options: [ { label: 'top-start', value: 'top-start' }, { label: 'top-end', value: 'top-end' }, { label: 'bottom-start', value: 'bottom-start' }, { label: 'bottom-end', value: 'bottom-end' }, ] }, { prop: 'color', type: 'string', }, { prop: 'showZero', type: 'boolean', }, ] } <V2Indicator label={5}> <V2Badge> Indicator Sandbox </V2Badge> </V2Indicator> ``` ## Offset Use the `offset` prop to change the position of the Indicator. It is useful when the Indicator component is used with children that have a border radius. ```jsx live <Layout.Group space={30}> <V2Indicator label={10}> <IconSymbol icon="face" size="xl" /> </V2Indicator> <V2Indicator label={10} offset={10}> <IconSymbol icon="face" size="xl" /> </V2Indicator> </Layout.Group> ``` ## Label Use the `label` prop to pass in the content that will be displayed within the Indicator. The value can be either a `number` or `string`. If no label is provided, then the Indicator will be styled as a smaller circle. ```jsx live <Box color="$primary1"> <Layout.Group space={30}> <V2Indicator label={'New'} offset={10}> <IconSymbol icon="face" size="lg" color="$web.semantic.color.border.status.subtle.info" /> </V2Indicator> <V2Indicator label={20} offset={10}> <IconSymbol icon="face" size="lg" color="$web.semantic.color.border.status.subtle.info" /> </V2Indicator> <V2Indicator label={100} offset={10}> <IconSymbol icon="face" size="lg" color="$web.semantic.color.border.status.subtle.info" /> </V2Indicator> <V2Indicator offset={10}> <IconSymbol icon="face" size="lg" color="$web.semantic.color.border.status.subtle.info" /> </V2Indicator> </Layout.Group> </Box> ``` ## Overflow count Use the `overflowCount` prop to show the Indicator label content with a `+` symbol when the Indicator label value has surpassed the overflowCount value. Default is `99`. ```jsx live () => { const [count, setCount] = useState(100); return ( <Layout.Stack> <Layout.Group space={30}> <V2Indicator label={count} overflowCount={10} offset={10}> <IconSymbol icon="face" size="xl" /> </V2Indicator> <V2Indicator label={count} offset={10}> <IconSymbol icon="face" size="xl" /> </V2Indicator> <V2Indicator label={count} overflowCount={100} offset={10}> <IconSymbol icon="face" size="xl" /> </V2Indicator> </Layout.Group> <Layout.Group space={30}> <V2Button onClick={() => setCount((old) => old + 1)}> Increment </V2Button> <V2Button variant="outline" onClick={() => setCount((old) => (old > 0 ? old - 1 : old))} > Decrement </V2Button> </Layout.Group> </Layout.Stack> ); }; ``` ## Show zero Use the `showZero={false}` prop to hide the Indicator when the label value is `0`. The default is set to `true`. ```jsx live <Layout.Group space={30}> <V2Indicator label={0}> <IconSymbol icon="mail" size={48} /> </V2Indicator> <V2Indicator label={0} showZero={false}> <IconSymbol icon="mail" size={48} /> </V2Indicator> </Layout.Group> ``` ## Color Use the `color` prop to change the color of the Indicator. ```jsx live <Layout.Group space={30}> <V2Indicator label={8} color="green"> <IconSymbol icon="mail" size={48} /> </V2Indicator> <V2Indicator label={100} color="$web.semantic.color.surface.container.status.warning.saturated" > <IconSymbol icon="mail" size={48} /> </V2Indicator> </Layout.Group> ``` ## Indicator type Use the `indicatorType` prop to pass additional description text that will be appended to the label text and read by a screen reader to provide the user context of the Indicator's role. This text will always remain hidden from display and is exclusively used for accessibility purposes. The default value is `Notifications`. ```jsx live <Layout.Group space={30}> <V2Indicator offset={5} label={20} indicatorType="emails"> <IconSymbol icon="mail" size={48} /> </V2Indicator> </Layout.Group> ``` ## Focusable element Indicator is not focusable. If a focusable element is wrapped with the Indicator you will need to pass an `aria-label` to the focusable element. The aria-label text should include the Indicator label content and information about the Indicator's role. For example `aria-label="Indicator with [label] notifications"`. Please see the example below for further details on implementation. ```jsx live () => { const [count, setCount] = useState(7); const overflowCount = 10; return ( <Layout.Stack space={10}> <V2Indicator label={count} overflowCount={overflowCount} offset={2}> <V2Button aria-label={ count > overflowCount ? `Indicator with ${overflowCount}+ notifications` : `Indicator with ${count} notifications` } > Indicator </V2Button> </V2Indicator> <Layout.Group> <V2Button onClick={() => setCount((old) => old + 1)}>+</V2Button> <V2Button variant="outline" onClick={() => setCount((old) => (old > 0 ? old - 1 : old))} > - </V2Button> </Layout.Group> </Layout.Stack> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2Indicator" propTypeName="V2IndicatorProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2ClassesTable title="V2Indicator" classes={[IndicatorClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> <h2>Focusable element</h2> Indicator is not focusable. If a focusable element is wrapped with the Indicator you will need to pass an `aria-label` to the focusable element. The aria-label text should include the Indicator label content and information about the Indicator's role. For example `aria-label="Indicator with [label] notifications"`. Please see the example below for further details on implementation. To avoid duplicate announcements, you can also pass the `noAnnounce` prop to the `V2Indicator` component. This will allow the wrapped focusable element to handle off-screen announcements instead. ```jsx live () => { const [count, setCount] = useState(7); const overflowCount = 10; return ( <Layout.Stack space={10}> <V2Indicator label={count} overflowCount={overflowCount} offset={2} indicatorType="items remaining" > <V2Button aria-label={ count > overflowCount ? `Indicator with ${overflowCount}+ items remaining` : `Indicator with ${count} items remaining` } > Indicator </V2Button> </V2Indicator> <Layout.Group> <V2Button onClick={() => setCount((old) => old + 1)} aria-label="Add item" > + </V2Button> <V2Button variant="outline" aria-label="Remove item" onClick={() => setCount((old) => (old > 0 ? old - 1 : old))} > - </V2Button> </Layout.Group> </Layout.Stack> ); }; ``` ```jsx live <V2Indicator label={1} offset={5} noAnnounce> <V2Avatar variant="3" onClick={() => console.log('there is a notification')} ariaLabel={`avatar with 1 notification indicated`} /> </V2Indicator> ``` <h2>Dynamic label content</h2> After initial load, anytime the Indicator label content is updated, a `role="alert"` attribute will be applied to ensure that screen readers will announce the updated content. Please see the example above for a demonstration of this in action. <h2>Character limit</h2> While there is no explicit limit on the number of text characters that can be used in the Indicator, be mindful that the wider the Indicator, the greater the risk of blocking surrounding information from view. <h2>Offset</h2> Like the character limit, be cognizant of the Indicator positioning in relation to the element it is paired with, particularly with icons that are sized dynamically. Avoid fixed values or large offsets that could potentially overlap or cover the paired icon or surrounding content. <h2>Color contrast</h2> As with all components, the color contrast of the text within the Indicator to the background color must be at least 4.5:1. Additionally, the background circle shape must have a minimum of 3:1 color contrast with the icon/element it's attached to as well as the surrounding background. Please find link for color contrast guide [Color Contrast](/web/accessibility/#color-contrast). <h2>Additional examples</h2> ```jsx live <Layout.Group space={30}> <V2Indicator label={0} indicatorType="unread emails"> <IconSymbol icon="mail" size={48} /> </V2Indicator> <V2Indicator label={0} showZero={false} indicatorType="unread emails"> <IconSymbol icon="mail" size={48} /> </V2Indicator> <V2Indicator label={'New'} offset={10} indicatorType="invitations"> <IconSymbol icon="face" size="xl" /> </V2Indicator> <V2Indicator label={20} offset={10} indicatorType="invitations"> <IconSymbol icon="face" size="xl" /> </V2Indicator> </Layout.Group> ``` </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={V2Indicator} keys={['indicatorV2']} /> ``` </Tab> --- id: indicator category: Data Display title: Indicator description: Adds an indicator to wrapped elements. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=23706-93557 subDirectory: Indicator/v1 --- <Tab label="Overview"> ```jsx import { Indicator } from '@uhg-abyss/web/ui/Indicator'; ``` ## Usage To apply, wrap the `Indicator` component around an existing element. By default the Indicator will be positioned to the top-right corner of the child element. Please note that there are accessibility concerns when utilizing this component and further information can be found on the Accessibility tab of this page as well as below in the [Indicator Type](#indicator-type) / [Focusable Element](#focusable-element) sections. For further details on implementation please see the various sections below. ```jsx sandbox { component: 'Indicator', inputs: [ { prop: 'label', type: 'string', }, { prop: 'offset', type: 'number', }, { prop: 'overflowCount', type: 'number', }, { prop: 'position', type: 'select', options: [ { label: 'top-start', value: 'top-start' }, { label: 'top-end', value: 'top-end' }, { label: 'bottom-start', value: 'bottom-start' }, { label: 'bottom-end', value: 'bottom-end' }, ] }, { prop: 'size', type: 'select', options: [ { label: 'small', value: 'small' }, { label: 'large', value: 'large' }, ] }, { prop: 'color', type: 'string', }, { prop: 'showZero', type: 'boolean', }, { prop: 'withBorder', type: 'boolean', }, ] } () => { return ( <Indicator label={5}> <Badge> Indicator Sandbox </Badge> </Indicator> ); }; ``` ## Size Use the `size` prop to change the size of the Indicator to `small` or `large`. The default is set to `small`. ```jsx live <Layout.Group space={30}> <Indicator size="small" label={5}> <IconSymbol icon="mail" size={48} /> </Indicator> <Indicator size="large" label={5}> <IconSymbol icon="mail" size={48} /> </Indicator> </Layout.Group> ``` ## Offset Use the `offset` prop to change the position of the Indicator. It is useful when the Indicator component is used with children that have border radius. ```jsx live <Layout.Group space={30}> <Indicator size="small" label={10}> <IconSymbol icon="face" size="xl" /> </Indicator> <Indicator size="small" label={10} offset={10}> <IconSymbol icon="face" size="xl" /> </Indicator> </Layout.Group> ``` ## Label Use the `label` prop to pass in the content that will be displayed within the Indicator. The value can be either a `number` or `string`. ```jsx live <Layout.Group space={30}> <Indicator size="large" label={'New'} offset={10}> <IconSymbol icon="face" size="xl" /> </Indicator> <Indicator size="large" label={20} offset={10}> <IconSymbol icon="face" size="xl" /> </Indicator> </Layout.Group> ``` ## Overflow count Use the `overflowCount` prop to show the Indicator label content with a `+` symbol when the Indicator label value has surpassed the overflowCount value. Default is `99`. ```jsx live () => { const [count, setCount] = useState(100); return ( <Layout.Stack> <Layout.Group space={30}> <Indicator size="small" label={count} overflowCount={10} offset={10}> <IconSymbol icon="face" size="xl" /> </Indicator> <Indicator size="small" label={count} offset={10}> <IconSymbol icon="face" size="xl" /> </Indicator> <Indicator size="small" label={count} overflowCount={100} offset={10}> <IconSymbol icon="face" size="xl" /> </Indicator> </Layout.Group> <Layout.Group space={30}> <Button onClick={() => setCount((old) => old + 1)}>Increment</Button> <Button variant="outline" onClick={() => setCount((old) => (old > 0 ? old - 1 : old))} > Decrement </Button> </Layout.Group> </Layout.Stack> ); }; ``` ## With border Use the `withBorder` prop to apply border around Indicator. The default is set to `false` ```jsx live <Layout.Group space={30}> <Indicator size="large" label={20} offset={10} withBorder> <IconSymbol icon="face" size="xl" /> </Indicator> <Indicator size="large" label={10} offset={10}> <IconSymbol icon="face" size="xl" /> </Indicator> </Layout.Group> ``` ## Show zero Use the `showZero={false}` prop to hide the Indicator when the label value is `0`. The default is set to `true`. ```jsx live <Layout.Group space={30}> <Indicator label={0}> <IconSymbol icon="mail" size={48} /> </Indicator> <Indicator label={0} showZero={false}> <IconSymbol icon="mail" size={48} /> </Indicator> </Layout.Group> ``` ## Color Use the `color` prop to change the color of the Indicator. Default value is set to `'$error1'`. ```jsx live <Layout.Group space={30}> <Indicator label={8} color="green"> <IconSymbol icon="mail" size={48} /> </Indicator> <Indicator label={100} color="$gray9"> <IconSymbol icon="mail" size={48} /> </Indicator> </Layout.Group> ``` ## Indicator type Use the `indicatorType` prop to pass additional description text that will be appended to the label text and read by a screen reader to provide the user context of the indicators role. This text will always remain hidden from display and is exclusively used for accessibility purposes. The default value is `Notifications`. ```jsx live <Layout.Group space={30}> <Indicator offset={5} label={20} indicatorType="emails"> <IconSymbol icon="mail" size={48} /> </Indicator> </Layout.Group> ``` ## Focusable element Indicator is not focusable. If a focusable element is wrapped with the Indicator you will need to pass an `aria-label` to the focusable element. The aria-label text should include the Indicator label content and information about the Indicator's role. For example `aria-label="Indicator with [label] notifications"`. Please see the example below for further details on implementation. ```jsx live () => { const [count, setCount] = useState(7); const overflowCount = 10; const buttonCssProps = { 'abyss-button-root': { fontSize: '$lg', fontWeight: '$bold', }, }; return ( <Layout.Stack space={10}> <Indicator label={count} overflowCount={overflowCount} offset={2}> <Button aria-label={ count > overflowCount ? `Indicator with ${overflowCount}+ notifications` : `Indicator with ${count} notifications` } > Indicator </Button> </Indicator> <Layout.Group> <Button css={buttonCssProps} size={25} onClick={() => setCount((old) => old + 1)} > + </Button> <Button css={buttonCssProps} size={25} variant="outline" onClick={() => setCount((old) => (old > 0 ? old - 1 : old))} > - </Button> </Layout.Group> </Layout.Stack> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={Indicator} rows={[ { name: 'children', type: 'ReactNode', description: 'The contents of the indicator component', }, { name: 'position', type: "'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' ", description: 'Changes the indicator position', }, { name: 'size', type: " 'small' | 'large' ", description: 'Size of Indicator', }, { name: 'label', type: 'number | string', description: 'Label of indicator component', }, { name: 'overflowCount', type: 'number', description: 'Over Flow count display for indicator', }, { name: 'showZero', type: 'boolean', description: 'Flag to hide label when value is 0', }, { name: 'offset', type: 'number', description: 'Change the indicator default position based on the position variant', }, { name: 'color', type: 'string', description: 'Color for indicator', }, { name: 'withBorder', type: 'boolean', description: 'Flag to show border around indicator', }, { name: 'indicatorType', type: 'string', description: 'Description of indicators role for accessibility purposes', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Indicator} rows={[ { name: 'indicator-root', description: 'Indicator root element', }, { name: 'indicator-container', description: 'Indicator container element', }, { name: 'indicator-label', description: 'Indicator label element', }, ]} /> ``` </Tab> <Tab label="Accessibility"> <h2>Focusable Element</h2> Indicator is not focusable. If a focusable element is wrapped with the Indicator you will need to pass an `aria-label` to the focusable element. The aria-label text should include the Indicator label content and information about the Indicator's role. For example `aria-label="Indicator with [label] notifications"`. Please see the example below for further details on implementation. ```jsx live () => { const [count, setCount] = useState(7); const overflowCount = 10; const buttonCssProps = { 'abyss-button-root': { fontSize: '$lg', fontWeight: '$bold', }, }; return ( <Layout.Stack space={10}> <Indicator label={count} overflowCount={overflowCount} offset={2} indicatorType="items remaining" > <Button aria-label={ count > overflowCount ? `Indicator with ${overflowCount}+ items remaining` : `Indicator with ${count} items remaining` } > Indicator </Button> </Indicator> <Layout.Group> <Button css={buttonCssProps} size={25} onClick={() => setCount((old) => old + 1)} aria-label="Add item" > + </Button> <Button css={buttonCssProps} size={25} variant="outline" aria-label="Remove item" onClick={() => setCount((old) => (old > 0 ? old - 1 : old))} > - </Button> </Layout.Group> </Layout.Stack> ); }; ``` <h2>Dynamic Label Content</h2> After initial load, anytime the Indicator label content is updated a `role="alert"` attribute will be applied to ensure that screen readers will announce the updated content. Please see the example above for a demonstration of this in action. <h2>Character Limit</h2> While there is no explicit limit on the number of text characters that can be used in the indicator, be mindful that the wider the indicator, the greater the risk of blocking surrounding information from view. <h2>Offset</h2> Like the character limit, be cognizant of the indicator positioning in relation to the element it is paired with, particularly with icons that are sized dynamically. Avoid fixed values or large offsets that could potentially overlap or cover the paired icon or surrounding content. <h2>Color Contrast</h2> As with all components, the color contrast of the text within the indicator to the background color must be at least 4.5:1. Additionally, the background circle shape must have a minimum of 3:1 color contrast with the icon/element it's attached to as well as the surrounding background. Please find link for color contrast guide [Color Contrast](/web/accessibility/#color-contrast). <h2>Additional Examples</h2> ```jsx live <Layout.Group space={30}> <Indicator label={0} indicatorType="unread emails"> <IconSymbol icon="mail" size={48} /> </Indicator> <Indicator label={0} showZero={false} indicatorType="unread emails"> <IconSymbol icon="mail" size={48} /> </Indicator> <Indicator size="large" label={'New'} offset={10} indicatorType="invitations"> <IconSymbol icon="face" size="xl" /> </Indicator> <Indicator size="large" label={20} offset={10} indicatorType="invitations"> <IconSymbol icon="face" size="xl" /> </Indicator> </Layout.Group> ``` </Tab> --- id: label category: Typography title: Label description: Renders an accessible label to provide explanatory and/or informative text for user interface components. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=641-11869 --- <Tab label="Overview"> ```jsx import { Label } from '@uhg-abyss/web/ui/Label'; ``` ```jsx sandbox { component: 'Label', inputs: [ { prop: 'children', type: 'string', }, { prop: 'id', type: 'string', }, { prop: 'color', type: 'string', }, { prop: 'size', type: 'string', }, { prop: 'fontWeight', type: 'select', options: [ { label: '$lighter', value: '$lighter' }, { label: '$light', value: '$light' }, { label: '$normal', value: '$normal' }, { label: '$bold', value: '$bold' }, ], }, ], } <Label size="$xl">First Name</Label> ``` ## Customization Use Label component to display an accessible label with theme styles. Control Label styles with props. - Size: The `size` prop accepts Abyss size tokens, `px`, `rem`, and `em` (Default is `'$md'`). - Weight: The `fontWeight` prop accepts `'bold'`, `'soft'`, and numeric font weights, such as `600`, `700`, `800`, etc. (Default is `$bold`). - Color: The `color` prop accepts Abyss color tokens, as well as HTML and hexidecimal colors (Default is `'$gray8'`). ```jsx live <> <Label size="sm" id="first name"> Small label </Label> <Label size="md">Medium label</Label> <Label size="lg">Large label</Label> <Label fontWeight="soft">Soft</Label> <Label>Bold</Label> <Label color="$primary1">Primary color</Label> <Label color="black">HTML color</Label> <Label color="#196ECF">Hexidecimal color</Label> </> ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={Label} rows={[ { name: 'color', type: 'string', description: 'Set the color of the label', }, { name: 'children', type: 'ReactNode', description: 'Set the text of the label', }, { name: 'fontWeight', type: 'string', description: 'Set the text weight of the label', }, { name: 'size', type: 'number | string', description: 'Set the size of the label', }, { name: 'sizes', type: 'shape', description: 'Default sizes of the label', }, { name: 'id', type: 'string', description: 'Creates an ID for the label', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Label} rows={[ { name: 'label-root', description: 'Label root element', }, ]} /> ``` </Tab> <Tab label="Accessibility"> Using this component will automatically get the correct labelling using `id` and `aria-labelledby`. Text selection is prevented when double clicking label, because `user-selection` is set to none on default. </Tab> --- id: layout category: Layout title: Layout description: Used to layout UI elements horizontally or vertically --- <Tab label="Overview"> ```jsx import { Layout } from '@uhg-abyss/web/ui/Layout'; ``` ## Layout.Group Used to align elements in a row. ```jsx sandbox { component: 'Layout.Group', inputs: [ { prop: 'space', type: 'number', }, { prop: 'alignLayout', type: 'select', options: [ { label: 'left', value: 'left' }, { label: 'center', value: 'center' }, { label: 'right', value: 'right' }, { label: 'between', value: 'between' }, { label: 'around', value: 'around' }, ], }, { prop: 'alignItems', type: 'select', options: [ { label: 'top', value: 'top' }, { label: 'center', value: 'center' }, { label: 'bottom', value: 'bottom' }, ], }, { prop: 'grow', type: 'boolean', }, ], } <Layout.Group> <div style={{ border: '1px solid black', padding: '15px', margin: '4px' }}> Group 1 </div> <div style={{ border: '1px solid black', padding: '10px', margin: '4px' }}> Group 2 </div> <div style={{ border: '1px solid black', padding: '5px', margin: '4px' }}> Group 3 </div> </Layout.Group> ``` ## Layout.Stack Used to align elements in a column. ```jsx sandbox { component: 'Layout.Stack', inputs: [ { prop: 'space', type: 'number', }, { prop: 'alignLayout', type: 'select', options: [ { label: 'left', value: 'left' }, { label: 'center', value: 'center' }, { label: 'right', value: 'right' }, ], }, { prop: 'alignItems', type: 'select', options: [ { label: 'left', value: 'left' }, { label: 'center', value: 'center' }, { label: 'right', value: 'right' }, ], }, { prop: 'grow', type: 'boolean', }, ], } <Layout.Stack> <div style={{ border: '1px solid black', padding: '15px', margin: '4px' }}> Stack Sandbox 1 </div> <div style={{ border: '1px solid black', padding: '10px', margin: '4px' }}> Stack Sandbox 2 </div> <div style={{ border: '1px solid black', padding: '5px', margin: '4px' }}> Stack Sandbox 3 </div> </Layout.Stack> ``` ## Combine Layout.Group and Layout.Stack Use `Stack` and `Group` together to make simple sets of rows and columns ```jsx live <React.Fragment> <h3>Stack</h3> <Layout.Stack> <Layout.Group> <Button>Group 1</Button> <Button>Group 1</Button> <Button>Group 1</Button> </Layout.Group> <Layout.Group> <Button>Group 2</Button> <Button>Group 2</Button> <Button>Group 2</Button> </Layout.Group> </Layout.Stack> </React.Fragment> ``` ## Layout.Group and Layout.Stack props ### Space Use the `space` property to set the spacing for a `Group` or `Stack`. The default is set to `8`. ```jsx live <Grid> <Grid.Col span="100%"> <h3>Group</h3> <Layout.Group> <Button>Group 1</Button> <Button>Group 2</Button> <Button>Group 3</Button> </Layout.Group> </Grid.Col> <Grid.Col span="100%"> <h3>Group - 20px space</h3> <Layout.Group space={20}> <Button>Group 1</Button> <Button>Group 2</Button> <Button>Group 3</Button> </Layout.Group> </Grid.Col> </Grid> ``` ```jsx live <Grid> <Grid.Col> <h3>Stack</h3> <Layout.Stack> <Button>Stack 1</Button> <Button>Stack 2</Button> <Button>Stack 3</Button> </Layout.Stack> </Grid.Col> <Grid.Col> <h3>Stack - 20px space</h3> <Layout.Stack space={20}> <Button>Stack 1</Button> <Button>Stack 2</Button> <Button>Stack 3</Button> </Layout.Stack> </Grid.Col> </Grid> ``` ### AlignLayout Use the `alignLayout` property to indicate the horizontal alignment of the items in a `Group` or `Stack`. - For a `Group`, the possible options are `left`, `center`, `right`, `between`, and `around`; the default is set to `left`. - For a `Stack`, the possible options are `left`, `center`, and `right`; the default is set to `center`. ```jsx live <React.Fragment> <h3>Group - left align - Default</h3> <Layout.Group> <div style={{ border: '1px solid black', padding: '15px', margin: '4px' }}> Group Default </div> <div style={{ border: '1px solid black', padding: '10px', margin: '4px' }}> Group Default </div> <div style={{ border: '1px solid black', padding: '5px', margin: '4px' }}> Group Default </div> </Layout.Group> <h3>Group - center align</h3> <Layout.Group alignLayout="center"> <div style={{ border: '1px solid black', padding: '15px', margin: '4px' }}> Group Center 1 </div> <div style={{ border: '1px solid black', padding: '10px', margin: '4px' }}> Group Center 2 </div> <div style={{ border: '1px solid black', padding: '5px', margin: '4px' }}> Group Center 3 </div> </Layout.Group> <h3>Group - right align</h3> <Layout.Group alignLayout="right"> <div style={{ border: '1px solid black', padding: '15px', margin: '4px' }}> Group Right 1 </div> <div style={{ border: '1px solid black', padding: '10px', margin: '4px' }}> Group Right 2 </div> <div style={{ border: '1px solid black', padding: '5px', margin: '4px' }}> Group Right 3 </div> </Layout.Group> <h3>Group - between align</h3> <Layout.Group alignLayout="between"> <div style={{ border: '1px solid black', padding: '15px', margin: '4px' }}> Group Between 1 </div> <div style={{ border: '1px solid black', padding: '10px', margin: '4px' }}> Group Between 2 </div> <div style={{ border: '1px solid black', padding: '5px', margin: '4px' }}> Group Between 3 </div> </Layout.Group> <h3>Group - around align</h3> <Layout.Group alignLayout="around"> <div style={{ border: '1px solid black', padding: '15px', margin: '4px' }}> Group Around 1 </div> <div style={{ border: '1px solid black', padding: '10px', margin: '4px' }}> Group Around 2 </div> <div style={{ border: '1px solid black', padding: '5px', margin: '4px' }}> Group Around 3 </div> </Layout.Group> </React.Fragment> ``` ```jsx live <React.Fragment> <h3>Stack - left align</h3> <Layout.Stack alignLayout="left"> <div style={{ border: '1px solid black', padding: '15px', margin: '4px' }}> Stack Left 1 </div> <div style={{ border: '1px solid black', padding: '10px', margin: '4px' }}> Stack Left 2 </div> <div style={{ border: '1px solid black', padding: '5px', margin: '4px' }}> Stack Left 3 </div> </Layout.Stack> <h3>Stack - center align - Default</h3> <Layout.Stack alignLayout="center"> <div style={{ border: '1px solid black', padding: '15px', margin: '4px' }}> Stack Default </div> <div style={{ border: '1px solid black', padding: '10px', margin: '4px' }}> Stack Default </div> <div style={{ border: '1px solid black', padding: '5px', margin: '4px' }}> Stack Default </div> </Layout.Stack> <h3>Stack - right align</h3> <Layout.Stack alignLayout="right"> <div style={{ border: '1px solid black', padding: '15px', margin: '4px' }}> Stack Right 1 </div> <div style={{ border: '1px solid black', padding: '10px', margin: '4px' }}> Stack Right 2 </div> <div style={{ border: '1px solid black', padding: '5px', margin: '4px' }}> Stack Right 3 </div> </Layout.Stack> </React.Fragment> ``` ### AlignItems Use the `alignItems` property to indicate the alignment of the items in a `Group` or `Stack`. For a `Group` the vertical alignment is adjusted, whereas for a `Stack` the horizontal alignment is adjusted. - For a `Group`, the possible options are `top`, `center`, and `bottom`. - For a `Stack`, the possible options are `left`, `center`, and `right`. The default is set to `center` in both cases. ```jsx live <React.Fragment> <h3>Group - top align</h3> <Layout.Group alignItems="top"> <div style={{ border: '1px solid black', padding: '15px', margin: '4px' }}> Group Top 1 </div> <div style={{ border: '1px solid black', padding: '10px', margin: '4px' }}> Group Top 2 </div> <div style={{ border: '1px solid black', padding: '5px', margin: '4px' }}> Group Top 3 </div> </Layout.Group> <h3>Group - center align - Default</h3> <Layout.Group> <div style={{ border: '1px solid black', padding: '15px', margin: '4px' }}> Group Default </div> <div style={{ border: '1px solid black', padding: '10px', margin: '4px' }}> Group Default </div> <div style={{ border: '1px solid black', padding: '5px', margin: '4px' }}> Group Default </div> </Layout.Group> <h3>Group - bottom align</h3> <Layout.Group alignItems="bottom"> <div style={{ border: '1px solid black', padding: '15px', margin: '4px' }}> Group Bottom 1 </div> <div style={{ border: '1px solid black', padding: '10px', margin: '4px' }}> Group Bottom 2 </div> <div style={{ border: '1px solid black', padding: '5px', margin: '4px' }}> Group Bottom 3 </div> </Layout.Group> </React.Fragment> ``` ```jsx live <React.Fragment> <h3>Stack - left align</h3> <Layout.Stack alignItems="left"> <div style={{ border: '1px solid black', padding: '15px', margin: '4px' }}> Stack Left 1 </div> <div style={{ border: '1px solid black', padding: '10px', margin: '4px' }}> Stack Left 2 </div> <div style={{ border: '1px solid black', padding: '5px', margin: '4px' }}> Stack Left 3 </div> </Layout.Stack> <h3>Stack - center align - Default</h3> <Layout.Stack alignItems="center"> <div style={{ border: '1px solid black', padding: '15px', margin: '4px' }}> Stack Default </div> <div style={{ border: '1px solid black', padding: '10px', margin: '4px' }}> Stack Default </div> <div style={{ border: '1px solid black', padding: '5px', margin: '4px' }}> Stack Default </div> </Layout.Stack> <h3>Stack - right align</h3> <Layout.Stack alignItems="right"> <div style={{ border: '1px solid black', padding: '15px', margin: '4px' }}> Stack Right 1 </div> <div style={{ border: '1px solid black', padding: '10px', margin: '4px' }}> Stack Right 2 </div> <div style={{ border: '1px solid black', padding: '5px', margin: '4px' }}> Stack Right 3 </div> </Layout.Stack> </React.Fragment> ``` ### Grow Use the `grow` property indicate whether the grouped components should be stretched to fill the space horizontally. The default is set to `false`. ```jsx live <React.Fragment> <h3>Group - default</h3> <Layout.Group> <Button>Item 1</Button> <Button>Item 2</Button> <Button>Item 3</Button> </Layout.Group> <h3>Group - grow</h3> <Layout.Group grow> <Button css={{ width: '100%' }}>Item 1</Button> <Button css={{ width: '100%' }}>Item 2</Button> <Button css={{ width: '100%' }}>Item 3</Button> </Layout.Group> </React.Fragment> ``` ```jsx live <React.Fragment> <h3>Stack - default</h3> <Layout.Stack> <Button>Item 1</Button> <Button>Item 2</Button> <Button>Item 3</Button> </Layout.Stack> <h3>Stack - grow</h3> <Layout.Stack grow> <Button css={{ width: '100%' }}>Item 1</Button> <Button css={{ width: '100%' }}>Item 2</Button> <Button css={{ width: '100%' }}>Item 3</Button> </Layout.Stack> </React.Fragment> ``` ### Width Use the optional `width` property to set the minimum width for each child element. ### Element types To change what type of html elements are displayed, use the props `as` and `childElementsAs`. They default to displaying as divs. ```jsx live <React.Fragment> <h3>Stack - as List</h3> <Layout.Stack as="ul" childElementsAs="li"> <Button>List Item 1</Button> <Button>List Item 2</Button> <Button>List Item 3</Button> </Layout.Stack> </React.Fragment> ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={Layout.Group} rows={[ { name: 'children', type: 'ReactNode', description: 'The element the group wraps', }, { name: 'width', type: 'number | string', description: 'Set the width of the group', }, { name: 'alignItems', type: 'top | center | bottom', description: 'Adjust the vertical alignment of items in the group', }, { name: 'alignLayout', type: 'left | center | right | between | around', description: 'Set the position of the group', }, { name: 'grow', type: 'boolean', description: 'Flag to stretch grouped components to fit evenly or not', }, { name: 'space', type: 'number', description: 'Distance between elements in the Group component', }, { name: 'as', type: 'string', description: 'Determine what type of html element the LayoutGroup container will render', }, { name: 'childElementsAs', type: 'string', description: 'Determine what type of html element the LayoutGroup elements will render', }, ]} /> ``` ```jsx render <Docs.PropsTable of={Layout.Insert} rows={[ { name: 'children', type: 'ReactNode', description: 'The element the inserted elements are between', }, { name: 'before', type: 'ReactNode | function', description: 'Insert element before children', }, { name: 'after', type: 'ReactNode | function', description: 'Insert element after children', }, { name: 'padding', type: ' string | number', description: 'The space between the inserted element and children', }, ]} /> ``` ```jsx render <Docs.PropsTable of={Layout.Space} rows={[ { name: 'space', type: 'string | number', description: 'The amount of space to place between components', }, ]} /> ``` ```jsx render <Docs.PropsTable of={Layout.Stack} rows={[ { name: 'children', type: 'ReactNode', description: 'The element the stack wraps', }, { name: 'width', type: 'number | string', description: 'Set the width of the stack', }, { name: 'alignItems', type: 'left | center | right', description: 'Adjust the horizontal alignment of items in the stack', }, { name: 'alignLayout', type: 'left | center | right', description: 'Set the position of the stack', }, { name: 'grow', type: 'boolean', description: 'Flag to stretch grouped components to fit evenly or not', }, { name: 'space', type: 'number', description: 'Distance between elements in the Group component', }, { name: 'as', type: 'string', description: 'Determine what type of html element the LayoutStack container will render', }, { name: 'childElementsAs', type: 'string', description: 'Determine what type of html element the LayoutStack elements will render', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Layout.Group} rows={[ { name: 'layout-group', description: 'Group root element', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Layout.Insert} rows={[ { name: 'insert-element-root', description: 'Insert root element', }, { name: 'insert-element-before', description: 'Insert before element', }, { name: 'insert-element-after', description: 'Insert after element', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Layout.Space} rows={[ { name: 'layout-space', description: 'Space root element', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Layout.Stack} rows={[ { name: 'layout-stack', description: 'Stack root element', }, ]} /> ``` </Tab> <Tab label="Accessibility"> For basic content layout, the normal divs should be sufficient. When using layout for semantic elements such as bulleted (ul) or ordered (ol) lists, be sure to use the `as` and `childElementsAs` props to correctly preserve the semantic structure. For example, the only valid children for ul and ol are li. Not doing so introduces semantic and code validation errors often reported in accessibility testing (including automated tools like Evinced). ```jsx live <React.Fragment> <h3>Our businesses</h3> <Layout.Group as="ul" childElementsAs="li"> <div> Visit <Button>UnitedHealthcare</Button> or one of other related businesses: </div> <Button>Optum</Button> <Button>UnitedHealth Group</Button> </Layout.Group> <br /> <br /> <h3>Our businesses</h3> <Layout.Stack grow as="ul" childElementsAs="li"> <div> Visit <Button>UnitedHealthcare</Button> or one of other related businesses: </div> <Button>Optum</Button> <Button>UnitedHealth Group</Button> </Layout.Stack> </React.Fragment> ``` </Tab> --- id: line category: Data Visualization title: Line slug: /web/ui/charts/line description: A graphical representation of data in a line-shaped graph. design: https://www.figma.com/design/NnKHAtlU3Q0Xq3RzN9PJe1/Abyss-Data-Visualization?node-id=3-22729 --- <Tab label="Overview"> Note: JPG and PNG download options are not compatible with Safari. As an alternative, please use the PDF option or take a screenshot. ```jsx import { Charts } from '@uhg-abyss/web/ui/Charts'; ``` ## Line chart Simple line chart with two dataSets having `title` and `subtitle` props passed. `xAxisLabel` and `yAxisLabel` are required props for chart. ```jsx live () => { const labels = [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', ]; const data = { labels, datasets: [ { label: 'Optum', data: [65, 59, 80, 81, 56, 55, 40], borderColor: '$primaryDvz1', backgroundColor: '$primaryDvz1', }, { label: 'Uhg', borderDash: [14, 14], data: [22, 65, 75, 85, 34, 23, 54], borderColor: '$secondaryDvz1', backgroundColor: '$secondaryDvz1', }, ], }; return ( <div> <Charts.Line data={data} title="Profile Views" subtitle="The feature shows you profile view statistics." xAxisLabel="Month" yAxisLabel="Views" /> </div> ); }; ``` ## Multi axis line chart Pass `yAxisID` to each dataSet and define the axis in the `scales` of the chart options passing in `options` prop to the chart. Configuration for the options can be found in the <ExitLink href="https://www.chartjs.org/docs/latest/">Chart Js</ExitLink> docs. ```jsx live () => { const labels = [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', ]; const data = { labels, datasets: [ { label: 'Dataset 1', data: [82, 29, 8, -90, 3, 57, 44], borderColor: '$primaryDvz1', backgroundColor: '$primaryDvz1', yAxisID: 'y', }, { label: 'Dataset 2', data: [-45, 90, 17, -68, 98, 53, 64], borderColor: '$secondaryDvz1', backgroundColor: '$secondaryDvz1', yAxisID: 'y1', }, ], }; return ( <div> <Charts.Line data={data} title="Multi Axis" subtitle="The feature shows you multi axis chart" xAxisLabel="Month" yAxisLabel="Values" chartType="Multi Axis Line Chart" options={{ scales: { y: { type: 'linear', display: true, position: 'left', title: { display: true, text: 'Dataset 1 Values', color: '#15A796', }, }, y1: { type: 'linear', display: true, position: 'right', title: { display: true, text: 'Dataset 2 Values', color: '#C72887', }, // grid line settings grid: { drawOnChartArea: false, // only want the grid lines for one axis to show up }, }, }, }} /> </div> ); }; ``` ## Point styling Use `pointStyle` prop in dataset to change the representation of the point on the chart and also can adjust the radius and background colors of the point by passing point properties like `pointRadius`,`pointHoverRadius`, `pointHoverBackgroundColor`. ```jsx live () => { const labels = ['Day 1', 'Day 2', 'Day 3', 'Day 4', 'Day 5', 'Day 6']; const data = { labels, datasets: [ { label: 'Dataset', data: [14, -5, 63, 31, 33, 86], borderColor: '$purpleDvz1', backgroundColor: '$purpleDvz3', pointHoverBackgroundColor: '$purpleDvz3', pointStyle: 'circle', pointRadius: 10, pointHoverRadius: 15, }, ], }; return ( <div> <Charts.Line data={data} title="Point Styling" xAxisLabel="Day" yAxisLabel="Value" options={{ plugins: { legend: { labels: { usePointStyle: true, boxHeight: 12, boxWidth: 12, }, }, tooltip: { usePointStyle: true, boxHeight: 12, boxWidth: 12, }, }, }} /> </div> ); }; ``` ## Line segment styling Using helper functions to style each segment. Gaps in the data ('skipped') are set to dashed lines and segments with values going 'down' are set to a different color. ```jsx live () => { const labels = [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', ]; const skipped = (ctx, value) => { return ctx.p0.skip || ctx.p1.skip ? value : undefined; }; const down = (ctx, value) => ctx.p0.parsed.y > ctx.p1.parsed.y ? value : undefined; const data = { labels, datasets: [ { label: 'My Segment Dataset', data: [65, 59, 'NaN', 48, 56, 57, 40], borderColor: '$primaryDvz1', segment: { borderColor: (ctx) => skipped(ctx, 'rgb(0,0,0,0.2)') || down(ctx, 'rgb(192,75,75)'), borderDash: (ctx) => skipped(ctx, [6, 6]), }, spanGaps: true, }, ], }; return ( <div> <Charts.Line data={data} title="Segment Styling" xAxisLabel="Month" yAxisLabel="Value" chartType="Segment Line Chart" options={{ fill: false, interaction: { intersect: false, }, radius: 0, }} /> </div> ); }; ``` ## Stepped line charts Pass `stepped` prop in dataset as `true` to make line chart styled as stepped. ```jsx live () => { const labels = ['Day 1', 'Day 2', 'Day 3', 'Day 4', 'Day 5', 'Day 6']; const data = { labels, datasets: [ { label: 'Stepped Dataset', data: [33, -60, 75, 95, 45, -78], borderColor: '$tangerineDvz1', fill: false, stepped: true, pointRadius: 5, pointHoverRadius: 5, }, ], }; return ( <div> <Charts.Line data={data} title="Stepped Chart" xAxisLabel="Day" yAxisLabel="Value" chartType="Stepped Line Chart" options={{ interaction: { intersect: false, axis: 'x', }, }} /> </div> ); }; ``` ## Zoom Use `enableZoom` prop to toggle zooming of chart. The default value is `false`. Configuration for the zoom options can be found in the <ExitLink href="https://www.chartjs.org/chartjs-plugin-zoom/latest/guide/options.html">Zoom Options</ExitLink> docs. ```jsx live () => { const labels = [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', ]; const data = { labels, datasets: [ { label: 'Dataset', data: [65, 59, 80, 81, 56, 55, 40], borderColor: '$primaryDvz1', backgroundColor: '$primaryDvz1', }, ], }; return ( <div> <Charts.Line data={data} title="Zoom Views" subtitle="Zooming capability of chart" xAxisLabel="Month" yAxisLabel="Views" enableZoom /> </div> ); }; ``` ## Data structure Data in the datasets can be different structures and can be found in the <ExitLink href="https://www.chartjs.org/docs/latest/general/data-structures.html">Data Structures</ExitLink> docs. ```jsx live () => { const data = { datasets: [ { label: 'Dataset', data: [ { x: '2016-12-25', y: 20 }, { x: '2016-12-26', y: 10 }, { x: '2016-12-27', y: 25 }, { x: '2016-12-28', y: 30 }, { x: '2016-12-29', y: 50 }, ], borderColor: '$primaryDvz1', backgroundColor: '$primaryDvz1', }, ], }; return ( <div> <Charts.Line data={data} title="Data Structure" subtitle="Structure of data" xAxisLabel="Date" yAxisLabel="Value" /> </div> ); }; ``` ## Options Use `options` prop to customize the chart level and dataset level. Configuration for the options can be found in the <ExitLink href="https://www.chartjs.org/docs/latest/general/options.html">Options</ExitLink> docs. ```jsx live () => { const labels = [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', ]; const data = { labels, datasets: [ { label: 'Optum', data: [65, 59, 80, 81, 56, 55, 40], borderColor: '$primaryDvz1', backgroundColor: '$primaryDvz1', }, { label: 'Uhg', data: [22, 65, 75, 85, 34, 23, 54], borderColor: '$secondaryDvz1', backgroundColor: '$secondaryDvz1', borderDash: [14, 14], }, ], }; return ( <div> <Charts.Line data={data} title="Options Config" subtitle="Options configuration for chart" xAxisLabel="Month" yAxisLabel="Views" options={{ plugins: { legend: { position: 'right', }, }, }} /> </div> ); }; ``` ## Chart description Use `chartDescription` prop to describe the chart and will be shown in chart description accordion below the view data table accordion. The default value of `chartDescription` is `null`. Whether displayed or not, the chart description accordion, including its content, are announced as the “long description” for the chart. ```jsx live () => { const labels = [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', ]; const data = { labels, datasets: [ { label: 'Optum', data: [65, 59, 80, 81, 56, 55, 40], borderColor: '$primaryDvz1', backgroundColor: '$primaryDvz1', }, { label: 'Uhg', data: [22, 65, 75, 85, 34, 23, 54], borderColor: '$secondaryDvz1', backgroundColor: '$secondaryDvz1', borderDash: [14, 14], }, ], }; return ( <div> <Charts.Line data={data} title="Chart Description" subtitle="Describe the chart" xAxisLabel="Month" yAxisLabel="Views" chartDescription={ 'Line chart with Uhg having more views in April and least views in January' } /> </div> ); }; ``` ## Chart type Use `chartType` prop to describe the type of line chart. The default value is `Line Chart`. ```jsx live () => { const labels = [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', ]; const data = { labels, datasets: [ { label: 'Unfilled', data: [62, 1, 9, -70, -96, 1, -28], fill: false, borderColor: '$primaryDvz1', backgroundColor: '$primaryDvz3', pointHoverBackgroundColor: '$primaryDvz3', pointStyle: 'triangle', pointRadius: 10, pointHoverRadius: 15, }, { label: 'Dashed', fill: false, borderDash: [12, 12], data: [-20, 71, 56, -30, -69, 50, 67], borderColor: '$secondaryDvz1', backgroundColor: '$secondaryDvz3', pointHoverBackgroundColor: '$secondaryDvz3', pointStyle: 'rectRot', pointRadius: 10, pointHoverRadius: 15, }, { label: 'Filled', fill: true, data: [-57, 20, 95, 34, 33, -77, -5], borderColor: '$tangerineDvz2', backgroundColor: '$tangerineDvz3', pointHoverBackgroundColor: '$tangerineDvz3', pointRadius: 10, pointHoverRadius: 15, }, ], }; return ( <div> <Charts.Line data={data} title="Line Styling" subtitle="line styles using fill option" xAxisLabel="Month" yAxisLabel="Value" chartType="Styled Line Chart" options={{ plugins: { legend: { display: true, labels: { usePointStyle: true, boxHeight: 12, boxWidth: 12, }, }, tooltip: { usePointStyle: true, boxHeight: 12, boxWidth: 12, }, }, }} /> </div> ); }; ``` ## Title offset Use `titleOffset` prop to change the heading level of graph title in a page. The default value is `1`. You can use titleOffset={1|2|3|4|5}. ```jsx live () => { const labels = [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', ]; const data = { labels, datasets: [ { label: 'Dataset', data: [65, 59, 80, 81, 56, 55, 40], borderColor: '$primaryDvz1', backgroundColor: '$primaryDvz1', }, ], }; return ( <div> <Charts.Line data={data} title="Title Offset" subtitle="Title heading level" xAxisLabel="Month" yAxisLabel="Views" titleOffset={3} /> </div> ); }; ``` ## Hiding dropdowns Use the `hideDataTable` prop to remove the "View Data Table" accordion dropdown below the chart. Use the `hideDownloadDropdown` prop to remove the download options dropdown in the upper right corner of the chart. The default setting for both options is `false`. ```jsx live () => { const labels = [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', ]; const data = { labels, datasets: [ { label: 'Optum', data: [65, 59, 80, 81, 56, 55, 40], borderColor: '$primaryDvz1', backgroundColor: '$primaryDvz1', }, { label: 'Uhg', borderDash: [14, 14], data: [22, 65, 75, 85, 34, 23, 54], borderColor: '$secondaryDvz1', backgroundColor: '$secondaryDvz1', }, ], }; return ( <div> <Charts.Line data={data} title="Profile Views" subtitle="The feature shows you profile view statistics." xAxisLabel="Month" yAxisLabel="Views" hideDataTable hideDownloadDropdown /> </div> ); }; ``` ## Showing dropdowns Use the `openDataTable` prop to expand the "View Data Table" accordion dropdown below the chart by default. The default is `false`. Setting to `true` expands the accordion by default, while setting it to `'always'` prevents the accordion from being collapsible, and is thus always open. ```jsx live () => { const labels = [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', ]; const data = { labels, datasets: [ { label: 'Optum', data: [65, 59, 80, 81, 56, 55, 40], borderColor: '$primaryDvz1', backgroundColor: '$primaryDvz1', }, { label: 'Uhg', borderDash: [14, 14], data: [22, 65, 75, 85, 34, 23, 54], borderColor: '$secondaryDvz1', backgroundColor: '$secondaryDvz1', }, ], }; return ( <div> <Charts.Line data={data} title="Profile Views" subtitle="The feature shows you profile view statistics." xAxisLabel="Month" yAxisLabel="Views" openDataTable="always" /> </div> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={Charts.Line} rows={[ { name: 'title', type: 'string', description: 'Title for the chart', }, { name: 'subtitle', type: 'string', description: 'Subtitle for the chart', }, { name: 'xAxisLabel', type: 'string', description: 'Label for the X-axis', }, { name: 'yAxisLabel', type: 'string', description: 'Label for the Y-axis', }, { name: 'data', type: 'object', description: 'Data input object for chart', }, { name: 'options', type: 'object', description: 'Custom chart options object', }, // { // name: 'enableZoom', // type: 'string', // description: 'Flag to toggle zooming for chart', // }, { name: 'chartDescription', type: 'string', description: 'Description of the chart', }, { name: 'titleOffset', type: 'number', description: 'Heading level of chart title', }, { name: 'chartType', type: 'string', description: 'Describes type of the chart', default: 'Line Chart', }, { name: 'hideDataTable', type: 'bool', default: 'false', description: 'hides the "View Data Table" accordion dropdown', }, { name: 'hideDownloadDropdown', type: 'bool', default: 'false', description: 'hides the download options dropdown', }, { name: 'openDataTable', type: 'bool | "always"', default: 'false', description: 'opens the "View Data Table" accordion dropdown by default', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={'Chart'} rows={[ { name: 'chart-container', description: 'Chart container', }, { name: 'chart-canvas-wrapper', description: 'Chart canvas wrapper element', }, { name: 'chart-canvas-header-wrapper', description: 'Chart canvas header wrapper element', }, { name: 'chart-heading-container', description: 'Chart heading container', }, { name: 'chart-heading-wrapper', description: 'Chart heading wrapper', }, { name: 'chart-canvas-container', description: 'Chart canvas container', }, { name: 'chart-title', description: 'Chart title', }, { name: 'chart-subtitle', description: 'Chart subtitle', }, { name: 'chart-download-dropdown', description: 'Chart download options dropdown', }, { name: 'chart-canvas', description: 'Chart canvas element', }, { name: 'chart-canvas-music', description: 'Chart canvas keyboard navigation element', }, ]} /> ``` </Tab> <Tab label="Accessibility"> <h2>Chart accessibility requirements</h2> - Text contrast must be 4.5:1 or greater - Single chart line color contrast must be 3:1 or greater - Multiple dataset must be more than a difference in color - For Line charts: Use change line type (dots, dashes) and icons for data points <h2>Chart “long description”</h2> - Whether displayed or not, the chart description accordion, including its content, are announced as the “long description” for the chart. ```jsx live () => { const labels = [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', ]; const data = { labels, datasets: [ { label: 'Optum', data: [65, 59, 80, 81, 56, 55, 40], borderColor: '$primaryDvz1', backgroundColor: '$primaryDvz1', }, { label: 'Uhg', data: [22, 65, 75, 85, 34, 23, 54], borderDash: [14, 14], borderColor: '$secondaryDvz1', backgroundColor: '$secondaryDvz1', }, ], }; return ( <div> <Charts.Line data={data} title="Profile Views" subtitle="The feature shows you profile view statistics." xAxisLabel="Month" yAxisLabel="Views" /> </div> ); }; ``` <h3> Reduced Motion </h3> Animations and transitions that have been changed when a user has `prefers-reduced-motion` set to `reduced` for all Data Visualizations: - No inflation of bars, sections or lines upon initial data rendering - Data point tooltip navigation has animation removed - View Data Table Accordion has transitions removed ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Tab', description: 'Moves focus to the next focusable element; focuses the cnavas chart', }, { name: 'Space', description: 'When focus is on the canvas, pressing Space will focus the first datapoint of the first dataset in the chart', }, { name: 'Arrow Right', description: 'Moves focus to the next data point', }, { name: 'Arrow Left', description: 'Moves focus to the previous data point', }, { name: 'Page Down', description: ' Moves focus to next dataset at current position (if not currently on last dataset)', }, { name: 'Page Up', description: ' Moves focus to previous dataset at current position (if not currently on first dataset)', }, { name: 'Home', description: 'Moves focus to first data point of current dataset', }, { name: 'End', description: 'Moves focus to last data point of current dataset', }, ]} /> ``` <h2> Known screen reader issues</h2> <h3>NVDA and JAWS</h3> Datapoint navigation announce tooltip content twice - The second time includes chart name </Tab> --- id: link-v2 category: Navigation title: V2Link description: Used to hyperlink text and other components. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=24-9582 subDirectory: Link/v2 sourceIsTS: true --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="Link"></Docs.V2MigrationBanner> ``` ```jsx import { V2Link } from '@uhg-abyss/web/ui/Link'; ``` ```jsx sandbox { component: 'V2Link', inputs: [ { prop: 'children', type: 'string', }, { prop: 'size', type: 'select', options: [ { label: '$xs', value: '$xs' }, { label: '$sm', value: '$sm' }, { label: '$md', value: '$md' }, { label: '$lg', value: '$lg' }, ], }, { prop: 'fontWeight', type: 'select', options: [ { label: '$normal', value: '$normal' }, { label: '$medium', value: '$medium' }, { label: '$bold', value: '$bold' }, ], }, { prop: 'variant', type: 'select', options: [ { label: 'default', value: 'default' }, { label: 'underlined', value: 'underlined' }, ], }, { prop: 'href', type: 'string', }, { prop: 'openNewWindow', type: 'boolean', }, ] } // Due to the limitations of the sandbox, the 'alt' and 'alt-underlined' variants are not shown here // See the "Variants" section for examples of these variants <V2Link href="/web/ui/link-v2"> Link Sandbox </V2Link> ``` ## Text The children of the V2Link component will be rendered as the text of the link. ```jsx live <V2Link href="/web/ui/link-v2">Insert link text here</V2Link> ``` ## Link action Use the `href` prop to set the route the link will navigate to. ```jsx live <Layout.Stack alignItems="left"> <V2Link href="https://www.google.com">Absolute Link</V2Link> <V2Link href="/web/ui/link-v2">Relative Link</V2Link> </Layout.Stack> ``` ### On click In some cases, a link may need to initiate an action, such as downloading a file, instead of navigate to a path. By omitting the `href` prop, the link will render as a button and the `onClick` prop can be used to set a custom function to be triggered when the link is clicked. See the <ExitLink href="https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=24-9705&t=q37ikheZnw7PtIfR-4">design documentation</ExitLink> for more details. Note that if both `href` and `onClick` are present, the component will render as a link. Clicking on it will navigate to the `href` route and call the `onClick` function. This is useful for providing side-effect behavior, such as tracking link clicks. ```jsx live () => { const { toast } = useToast(); return ( <V2Link onClick={() => { toast.show({ title: 'Link Clicked', message: 'That link was actually a button!', variant: 'success', }); }} > Show Toast </V2Link> ); }; ``` ## Variant Use the `variant` prop to change the styling of the Link. The possible options are `'default'`, `'underlined'`, `'alt'`, and `'alt-underlined'`. The `'underlined'` and `'alt-underlined'` variants should only be used when the Link is embedded in a block of text and/or when using the alt color scheme to provide clear visual distinction. See the <ExitLink href="https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=24-9728&t=mH6MOBSaJzz5orPF-4">design documentation</ExitLink> for more details. ```jsx live <Layout.Stack alignItems="left" grow> <Box color="$white"> <V2Link href="/web/ui/link-v2" variant="default"> Default Variant </V2Link> </Box> <Box color="$white"> <V2Link href="/web/ui/link-v2" variant="underlined"> Underlined Variant </V2Link> </Box> <Box color="$primary1"> <V2Link href="/web/ui/link-v2" variant="alt"> Alt Variant </V2Link> </Box> <Box color="$primary1"> <V2Link href="/web/ui/link-v2" variant="alt-underlined"> Alt Underlined Variant </V2Link> </Box> </Layout.Stack> ``` ## Font weight Use the `fontWeight` prop to set the text weight of the link. The possible options are `'$normal'`, `'$medium'`, and `'$bold'`. The default is set to `'$medium'`. ```jsx live <Layout.Stack alignItems="left"> <V2Link fontWeight="$normal" href="/web/ui/link-v2"> Normal Weight </V2Link> <V2Link href="/web/ui/link-v2">Medium Weight (Default)</V2Link> <V2Link fontWeight="$bold" href="/web/ui/link-v2"> Bold Weight </V2Link> </Layout.Stack> ``` ## Size Use the `size` prop to set the size of the link. The possible options are `'$xs'`, `'$sm'`, `'$md'`, and `'$lg'`. The default is set to `'$md'`. ```jsx live <Layout.Stack alignItems="left"> <V2Link size="$xs" href="/web/ui/link-v2"> Extra Small </V2Link> <V2Link size="$sm" href="/web/ui/link-v2"> Small </V2Link> <V2Link href="/web/ui/link-v2">Medium (Default)</V2Link> <V2Link size="$lg" href="/web/ui/link-v2"> Large </V2Link> </Layout.Stack> ``` ## Inserting elements To insert an [IconSymbol](/web/ui/icon-symbol) into the `V2Link`, use the `beforeIcon` and `afterIcon` props. Both props accept either a string (the name of the IconSymbol to use) or an object of the following type: ```ts { icon: string; variant: 'filled' | 'outlined'; } ``` ```jsx live <Layout.Stack alignItems="left"> <V2Link beforeIcon="chevron_left" href="/web/ui/link-v2"> Before Link </V2Link> <V2Link afterIcon="chevron_right" href="/web/ui/link-v2"> After Link </V2Link> <V2Link beforeIcon={{ icon: 'info', variant: 'outlined' }} afterIcon="chevron_right" href="/web/ui/link-v2" > Lorem ipsum odor amet, consectetuer adipiscing elit. Feugiat etiam scelerisque cubilia sem torquent pellentesque facilisi. Pulvinar sapien posuere sollicitudin quam vehicula penatibus fermentum vehicula. </V2Link> </Layout.Stack> ``` ## Open in a new tab or window Use the `openNewWindow` prop to specify whether links open in a new tab or window. By default, `openNewWindow` is false for relative links, and true for absolute links. ```jsx live <Layout.Stack alignItems="left"> <Label>Relative Link</Label> <V2Link href="/web/ui/link-v2">Relative - Same Window/Tab</V2Link> <V2Link href="/web/ui/link-v2" openNewWindow> Relative - New Window/Tab </V2Link> <Label>Absolute Link</Label> <V2Link href="https://www.google.com" openNewWindow={false}> Absolute - Same Window/Tab </V2Link> <V2Link href="https://www.google.com">Absolute - New Window/Tab</V2Link> </Layout.Stack> ``` ## Standard anchor The V2Link component has several built in features like router and external link checks. To disable these features and use the V2Link component as a default anchor tag use the `isStandardAnchor` prop. This can be useful when using `tel` or `mailto` hrefs as well as download links. The default setting is `false`. ```jsx live <Layout.Stack alignItems="left"> <V2Link href="tel:+15551234567" isStandardAnchor> (555) 123-4567 </V2Link> <V2Link href="mailto:example@example.com" isStandardAnchor> example@example.com </V2Link> </Layout.Stack> ``` ## Active links If a link element href matches the current location path, the class `abyss-link-active` will be applied to the root element. Use this class to target the styling of an active link. To override the path matching detection, use the `isActive` prop to directly add the `abyss-link-active` class to a particular link. ```jsx live () => { const activeStyle = { color: '$core.color.neutral.80', '&:hover': { color: '$core.color.neutral.90', }, '&:active': { color: '$core.color.neutral.100', }, }; return ( <Layout.Stack alignItems="left"> <V2Link css={{ 'abyss-link-active': activeStyle, }} href="/web/ui/link-v2" > Active link using path detection </V2Link> <V2Link css={{ 'abyss-link-active': activeStyle, }} href="/web/ui/nav-menu" isActive > Active link using isActive </V2Link> </Layout.Stack> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2Link" propTypeName="V2LinkProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2ClassesTable title="V2Link" classes={[LinkClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> V2Link is built on the standard HTML `<a>` element for maximum accessibility and compatibility. It provides the icon with alt text for links that open new tabs or windows. <h2>Avoid "Naked" Blue Text Links</h2> Bold blue text is rarely enough by itself to indicate a link, especially in body copy. Use the `'underlined'` or `'alt-underlined'` variants (following the original HTML standard) or add a decorative icon for maximum accessibility and usability. <h2>Decorative vs. Content Icons</h2> Only when an icon is used as link itself (not recommended), or provides additional information (like the "new window" icons) should it have text alternatives. <h3>Text Alternatives</h3> Do not add text alternatives when the icon duplicates the visible link. Doing so is redundant and will be confusing to screen reader users. If alt text were used in the decorative icon examples below, screen readers would announce the alt text like this: - "Help graphic Help link" - "Previous graphic Previous page link" - "Next Page Next graphic link" ```jsx live <Layout.Stack alignItems="left"> <b>New window link with icon</b> <V2Link href="https://www.google.com">Link to another site</V2Link> <b>Links with decorative icons (no alt text)</b> <V2Link beforeIcon="help" href="/web/ui/link-v2?tab=accessibility"> Help </V2Link> <V2Link beforeIcon="chevron_left" href="/web/ui/link-v2?tab=accessibility"> Previous page </V2Link> <V2Link afterIcon="chevron_right" href="/web/ui/link-v2?tab=accessibility"> Next page </V2Link> <b>Body copy link</b> <V2Link href="/web/ui/link-v2?tab=accessibility" variant="underlined"> Link on this site </V2Link> </Layout.Stack> ``` <h2>Avoid Using Links for Buttons</h2> Links should only be used for navigating between pages (or their equivalents) on a website. If the `href` prop is not defined, links are implemented as HTML `<button>`s. Use the [Button](/web/ui/button) component whenever possible for these cases. This is especially true if the element is not used for site navigation. </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={Link} keys={['linkV2']} /> ``` </Tab> --- id: link category: Navigation title: Link description: Used to hyperlink text and other components. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=3578-23321 subDirectory: Link/v1 --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="Link"></Docs.V2MigrationBanner> ``` ```jsx import { Link } from '@uhg-abyss/web/ui/Link'; ``` ```jsx sandbox { component: 'Link', inputs: [ { prop: 'children', type: 'string', }, { prop: 'color', type: 'string', }, { prop: 'size', type: 'string', }, { prop: 'fontWeight', type: 'select', options: [ { label: '$lighter', value: '$lighter' }, { label: '$light', value: '$light' }, { label: '$normal', value: '$normal' }, { label: '$bold', value: '$bold' }, ], }, { prop: 'variant', type: 'select', options: [ { label: 'underline', value: 'underline' }, { label: 'native', value: 'native' }, ], }, { prop: 'href', type: 'string', defaultValue: '/web/ui/link', }, { prop: 'isDisabled', type: 'boolean', }, ] } <Link>Link Sandbox</Link> ``` ## Text Change the children of the link to set the text. ```jsx live <Link href="/web/ui/link">Insert link text here</Link> ``` ## Href Use the `href` prop to set the link to a separate page. ```jsx live <Layout.Stack alignItems="left"> <Link href="https://www.google.com">Regular Link</Link> <Link href="/web/ui/link">Based On Root Path</Link> </Layout.Stack> ``` ## isDisabled If `isDisabled` or no `href` prop is passed, the link becomes a native `<button>` element. ```jsx live <Layout.Stack alignItems="left"> <Link onClick={() => console.log('onClick triggered!')}>Enabled Link</Link> <Link isDisabled>Disabled Link</Link> </Layout.Stack> ``` ## Variant Use the `variant` prop to change the styling of the Link. The `variant` property defaults to `'underline'`. The `'native'` variant is better suited for links with long text or having multiple lines. ```jsx live <Layout.Stack alignItems="left"> <Link href="https://www.google.com" variant="underline"> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum quis eros vel nibh suscipit rhoncus porta in nulla. Mauris nisl sem, semper sit amet faucibus id, lacinia cursus odio. </Link> <Link href="https://www.google.com" variant="native"> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum quis eros vel nibh suscipit rhoncus porta in nulla. Mauris nisl sem, semper sit amet faucibus id, lacinia cursus odio. </Link> </Layout.Stack> ``` ## Color Use the `color` prop to set the color of the link. The default is set to `interactive1`. ```jsx live <Layout.Stack alignItems="left"> <Link color="green" colorHover="darkGreen" href="/web/ui/link"> Regular color </Link> <Link color="$primary1" colorHover="$interactive1" href="/web/ui/link"> Primary color </Link> <Link color="#FF0000" colorHover="#AA0000" href="/web/ui/link"> Hexadecimal color </Link> </Layout.Stack> ``` ## Font weight Use the `fontWeight` prop to set the text weight of the link. Possible options are `soft` or `bold`. The default is set to `soft`. ```jsx live <Layout.Stack alignItems="left"> <Link href="/web/ui/link">soft weight - default</Link> <Link fontWeight="bold" href="/web/ui/link"> bold weight </Link> </Layout.Stack> ``` ## Size Use the `size` prop to set the size of the link. The default is set to `md`. ```jsx live <Layout.Stack alignItems="left"> <Link size="$sm" href="/web/ui/link"> Small / 14px </Link> <Link href="/web/ui/link">Medium / 16px</Link> <Link size="$lg" href="/web/ui/link"> Large / 18px </Link> <Link size="30px" href="/web/ui/link"> Custom / 30px </Link> </Layout.Stack> ``` ## Inserting elements Insert elements into the Link component using the `before` and `after` props. ```jsx live <Layout.Stack alignItems="left"> <Link before={<IconSymbol icon="chevron_left" />} href="/web/ui/link"> Before Link </Link> <Link after={<IconSymbol icon="chevron_right" />} href="/web/ui/link"> After Link </Link> </Layout.Stack> ``` ## Open link in a new tab or window Use the `openNewWindow` prop to specify whether links open in a new tab or window. By default, `openNewWindow` is false for relative links, and true for absolute links. ```jsx live <Layout.Stack alignItems="left"> <Label>Relative Link</Label> <Link href="/web/ui/link">Relative - Same Window/Tab</Link> <Link href="/web/ui/link" openNewWindow> Relative - New Window/Tab </Link> <Label>Absolute Link</Label> <Link href="https://www.google.com" openNewWindow={false}> Absolute - Same Window/Tab </Link> <Link href="https://www.google.com">Absolute - New Window/Tab</Link> </Layout.Stack> ``` ## Standard anchor The Link component has several built in features like router and external link checks. To disable these features and use the Link component as a default anchor tag use the `isStandardAnchor` prop. This can be useful when using telephone or mailto href's as well as download links. The default setting is `false`. ```jsx live <Layout.Stack alignItems="left"> <Link href="tel:+123456789" isStandardAnchor> Call Now </Link> <Link href="mailto:m.bluth@example.com" isStandardAnchor> Email </Link> </Layout.Stack> ``` ## Applying styles to active links If a link element `href` matches the current location path, the class `abyss-link-active` will be applied to the root element. Use this class to target the styling of an active link. To override the path matching detection, use the `isActive` prop to directly add the `abyss-link-active` class to a particular link. ```jsx live () => { const activeStyle = { color: '$interactive4', '&:hover': { borderColor: '$interactive5', color: '$interactive5', }, }; return ( <Layout.Stack alignItems="left"> <Link css={{ 'abyss-link-active': activeStyle, }} href="/web/ui/link" > Active link using path detection </Link> <Link css={{ 'abyss-link-active': activeStyle, }} href="/web/ui/nav-menu" isActive > Active link using isActive </Link> </Layout.Stack> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={Link} rows={[ { name: 'before', type: 'ReactNode', description: 'Insert element into link component before children', }, { name: 'after', type: 'ReactNode', description: 'Insert element into link component after children', }, { name: 'href', type: 'string', description: 'Set the URL of the link', }, { name: 'color', type: 'string', description: 'Set the color of the link', }, { name: 'colorHover', type: 'string', description: 'Set the color of the link when it is hovered', }, { name: 'children', type: 'ReactNode', description: 'Set the text of the link', }, { name: 'fontWeight', type: 'string', description: 'Flag to set font weight of link', }, { name: 'size', type: 'number | string', description: 'Set the size of the link', }, { name: 'sizes', type: 'shape', description: 'Default sizes of the link', }, { name: 'variant', type: "'underline' | 'native' | 'custom'", description: 'Indicate whether the items contained in link should be underlined', }, { name: 'hideIcon', type: 'boolean', description: 'Flag to hide icon', }, { name: 'openNewWindow', type: 'boolean', description: 'Flag to set link to open in a new window', }, { name: 'onClick', type: 'function', description: 'Used to trigger a custom function when the link is clicked', }, { name: 'isDisabled', type: 'boolean', description: 'Flag to enable/disable the link', }, { name: 'isStandardAnchor', type: 'boolean', description: 'Flag to use link as a default anchor tag', }, { name: 'isActive', type: 'boolean', description: 'Flag to set active state of link', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Link} rows={[ { name: 'link-root', description: 'Link root element', }, { name: 'link-active', description: 'Link root element when active', }, { name: 'link-icon', description: 'Link icon element', }, { name: 'link-icon-wrapper', description: 'Link icon wrapper element', }, ]} /> ``` </Tab> <Tab label="Accessibility"> A link widget provides an interactive reference to a resource. The target resource can be either external or local, i.e., either outside or within the current page or application. Adheres to the <ExitLink href="https://www.w3.org/TR/wai-aria-practices-1.2/#link">Link WAI-ARIA design pattern</ExitLink>. ```jsx live <Layout.Stack alignItems="left"> <Link href="https://www.google.com">Regular Link</Link> <Link href="/web/ui/link">Based On Root Path</Link> </Layout.Stack> ``` ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Enter', description: 'Executes the link and moves focus to the link target.', }, ]} /> ``` The accessible name for the link must include the visible link text in its entirety. For example, if the visible link text is "Health Plans” the accessible name must include "Health Plans”. Preferably, the visible link text should precede any supplementary text in the accessible name. ```jsx live <Link href="/web/ui/link">Health Plans</Link> ``` <br /> Keyboard operation: a keyboard only user must be able to tab to the link, and activate it with the enter key. <h3> Reduced Motion </h3> Animations and transitions that have been changed when a user has `prefers-reduced-motion` set to `reduced`: - Animation of `Link` underline expanding from the center is removed </Tab> --- id: loading-overlay category: Overlay title: LoadingOverlay description: Focuses the user's attention on one task or piece of information. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=641-11885 --- <Tab label="Overview"> Disclaimer All code examples on this page are not editable but can be copied and pasted into your project. ```jsx import { LoadingOverlay } from '@uhg-abyss/web/ui/LoadingOverlay'; ``` ```jsx sandbox { component: 'LoadingOverlay', inputs: [ { prop: 'loadingTitle', type: 'string', }, { prop: 'loadingMessage', type: 'string', }, { prop: 'statusTitle', type: 'string', }, { prop: 'statusMessage', type: 'string', }, { prop: 'statusIcon', type: 'select', options: [ { label: 'success', value: 'success' }, { label: 'error', value: 'error' }, { label: 'warning', value: 'warning' }, { label: 'info', value: 'info' }, ], }, { prop: 'width', type: 'string', }, { prop: 'hideIcon', type: 'boolean' }, { prop: 'isDismissable', type: 'boolean', }, ], } () => { const [isLoading, setLoading] = useState(false); const [isOpen, setIsOpen] = useState(false); const { setCountdownTime } = useCountdown({ onCompleted: () => { setLoading(false); setIsOpen(true); } }); const triggerLoading = () => { setLoading(true); setCountdownTime(3 * 1000); }; const handleClose = () => { setIsOpen(false) }; return ( <LoadingOverlay loadingTitle="Please Wait" loadingMessage="Retrieving Information." ariaLoadingLabel="Example loading aria label" statusTitle="Status update" statusMessage="Sample message..." isLoading={isLoading} isOpen={isOpen} isDismissable onClose={handleClose} > <Card css={{ 'abyss-card-root': { height: 300, display: 'flex', justifyContent: 'center', alignItems: 'center', backgroundColor: '$gray4', }, }}> <Button onClick={triggerLoading}> Open LoadingOverlay </Button> </Card> </LoadingOverlay> ); } ``` ## Usage There are two main states to LoadingOverlay: the loading state and the loaded state. - In the loading state (when `isLoading` is set to `true`), a loading spinner will appear on the left, and the `loadingTitle` and `loadingMessage` props will be used as the text next to it. - Once loading has completed (when `isLoading` is set to `false`), the display changes: the `statusIcon` prop is used to create an icon on the left to reflect the application state after the load (ex. an error icon if something went wrong, or a success icon if data was submitted), and the `statusTitle` and `statusMessage` props will be used as the text next to it. In this state, the overlay can be closed when the `isDismissable` prop is set to `true`. ### useOverlay Using the [useOverlay](/web/hooks/use-overlay) hook allows you to open the overlay and pass data into it. See the [hook documentation](/web/hooks/use-overlay) for more information on its usage. ```jsx render-no-edit () => { const loadingOverlay = useOverlay('useOverlay-loading'); const state = loadingOverlay.getState(); return ( <React.Fragment> <Layout.Group alignItems="center" grow> <Button onClick={() => loadingOverlay.open({ isLoading: true, loadingTitle: 'Example Loading Title', ariaLoadingLabel: 'Example loading aria label', loadingMessage: 'Example loading message', }) } > Open Overlay - Loading </Button> <Button onClick={() => loadingOverlay.open({ isLoading: false, statusTitle: 'Example Status Title', statusMessage: 'Example status message', statusIcon: 'info', }) } > Open Overlay - Not Loading </Button> <Button onClick={() => loadingOverlay.close()}>Close Overlay</Button> </Layout.Group> <pre style={{ marginTop: 20 }}> Overlay State: {JSON.stringify(state, null, 2)} </pre> <br /> <LoadingOverlay width={400} model="useOverlay-loading"> <Card css={{ 'abyss-card-root': { height: 100, display: 'flex', backgroundColor: '$gray4', }, }} > <p>Loading Title: {state.data && state.data.loadingTitle}</p> </Card> <Card css={{ 'abyss-card-root': { height: 100, display: 'flex', backgroundColor: '$gray4', }, }} > <p>Status Title: {state.data && state.data.statusTitle}</p> </Card> </LoadingOverlay> </React.Fragment> ); }; ``` ### useState Use the `useState` hook to set the open and loading states of the loading overlay. ```jsx render-no-edit () => { const [isLoading, setLoading] = useState(false); const { setCountdownTime, formattedTime } = useCountdown({ onCompleted: () => { setLoading(false); }, }); const triggerLoading = () => { setLoading(true); setCountdownTime(3000); }; return ( <LoadingOverlay loadingTitle="This is the loadingTitle prop." loadingMessage={`This overlay will close itself in ${formattedTime}`} ariaLoadingLabel="This is the ariaLoadingLabel prop." isLoading={isLoading} > <Card css={{ 'abyss-card-root': { height: 250, display: 'flex', justifyContent: 'center', alignItems: 'center', backgroundColor: '$gray4', }, }} > <Button onClick={triggerLoading}>Open LoadingOverlay</Button> </Card> </LoadingOverlay> ); }; ``` ## Loading title Use the `loadingTitle` prop to set the title of the loading overlay when it is in the loading state. ```jsx render-no-edit <LoadingOverlay loadingTitle="Custom Title Here" isLoading> <Card css={{ 'abyss-card-root': { height: 250, display: 'flex', justifyContent: 'center', alignItems: 'center', backgroundColor: '$gray4', }, }} /> </LoadingOverlay> ``` ## Loading message Use the `loadingMessage` prop to set the description of the loading overlay when it is in the loading state. ```jsx render-no-edit () => { return ( <LoadingOverlay loadingTitle="Loading..." loadingMessage="Custom Description Here" ariaLoadingLabel="Custom loading label" isLoading > <Card css={{ 'abyss-card-root': { height: 250, display: 'flex', justifyContent: 'center', alignItems: 'center', backgroundColor: '$gray4', }, }} /> </LoadingOverlay> ); }; ``` ## Loading icon Use the `loadingIcon` prop to set an icon to be displayed inside of the loading spinner. ```jsx render-no-edit () => { return ( <LoadingOverlay loadingTitle="Loading Icon Example" loadingMessage="The icon appears inside of the loading spinner" ariaLoadingLabel="Loading aria label" isLoading loadingIcon={ <IconSymbol color="$primary1" icon="upload_file" size="35px" /> } > <Card css={{ 'abyss-card-root': { height: 250, display: 'flex', justifyContent: 'center', alignItems: 'center', backgroundColor: '$gray4', }, }} /> </LoadingOverlay> ); }; ``` ## Status title Use the `statusTitle` prop to set the title of the loading overlay when loading has completed. ```jsx render-no-edit <LoadingOverlay isOpen statusTitle="This is the statusTitle prop."> <Card css={{ 'abyss-card-root': { height: 250, display: 'flex', justifyContent: 'center', alignItems: 'center', backgroundColor: '$gray4', }, }} /> </LoadingOverlay> ``` ## Status message Use the `statusMessage` prop to set the description of the loading overlay when loading has completed. ```jsx render-no-edit <LoadingOverlay isOpen statusTitle="Loading Complete..." statusMessage="This is the statusMessage prop." > <Card css={{ 'abyss-card-root': { height: 250, display: 'flex', justifyContent: 'center', alignItems: 'center', backgroundColor: '$gray4', }, }} /> </LoadingOverlay> ``` ## Status icon Use the `statusIcon` prop to set the icon that will be displayed when loading has completed. Possible options are `success`, `error`, `warning`, and `info`. The default is `info`. You can hide the icon with the `hideIcon` prop. ```jsx render-no-edit () => { const [isOpen, setIsOpen] = useState(); const [statusIcon, setStatusIcon] = useState(); const handleClick = (statusIcon) => { setStatusIcon(statusIcon); setIsOpen(true); }; return ( <LoadingOverlay isOpen={isOpen} statusIcon={statusIcon} statusTitle="Status Icon Example" statusMessage="Your message goes here" isDismissable onClose={() => setIsOpen(false)} > <Card css={{ 'abyss-card-root': { height: 250, display: 'flex', justifyContent: 'center', alignItems: 'center', backgroundColor: '$gray4', }, }} > <Layout.Group> <Button onClick={() => handleClick('info')}>Info</Button> <Button onClick={() => handleClick('success')}>Success</Button> <Button onClick={() => handleClick('warning')}>Warning</Button> <Button onClick={() => handleClick('error')}>Error</Button> </Layout.Group> </Card> </LoadingOverlay> ); }; ``` ## isDismissable Use the `isDismissable` prop to determine whether the overlay can be closed after loading is complete. Use this prop with the [useState](#usestate) hook if there are situations where the user can take another action after dismissing the overlay. The default is `false`. You may want to set it to `false` in cases such as when a widget fails to load and cannot be used. The default is `false`. ```jsx render-no-edit () => { const [isOpen, setIsOpen] = useState(true); return ( <React.Fragment> <LoadingOverlay statusIcon="error" statusTitle="Non-Dismissable Overlay" statusMessage="This error message cannot be dismissed." isOpen > <Card css={{ 'abyss-card-root': { height: 200, backgroundColor: '$gray4', }, }} /> </LoadingOverlay> <LoadingOverlay statusIcon="error" statusTitle="Dismissable Overlay" statusMessage="This error message can be dismissed." onClose={() => setIsOpen(false)} isOpen={isOpen} isDismissable > <Card css={{ 'abyss-card-root': { height: 200, display: 'flex', justifyContent: 'center', alignItems: 'center', backgroundColor: '$gray4', }, }} > <Button onClick={() => setIsOpen(true)}>Reopen Overlay</Button> </Card> </LoadingOverlay> </React.Fragment> ); }; ``` ## isOpen Use the `isOpen` prop to set whether the overlay is open or not. Use this prop with the [useState](#usestate) hook to change the overlay between open and closed. The default is `false`. ```jsx render-no-edit () => { return ( <React.Fragment> <LoadingOverlay statusTitle="isOpen set to true" isOpen> <Card css={{ 'abyss-card-root': { height: 250, display: 'flex', justifyContent: 'center', alignItems: 'center', backgroundColor: '$gray4', }, }} > <Text> This text will be covered by the overlay when isOpen is set to true. </Text> </Card> </LoadingOverlay> <LoadingOverlay statusTitle="isOpen set to false"> <Card css={{ 'abyss-card-root': { height: 250, display: 'flex', justifyContent: 'center', alignItems: 'center', backgroundColor: '$gray4', }, }} > <Text> isOpen is set to false, so the overlay will not be displayed </Text> </Card> </LoadingOverlay> </React.Fragment> ); }; ``` ## isLoading Use the `isLoading` prop to set whether the overlay is loading or not. Use this prop with the [useState](#usestate) hook to set the loading state based on the status of the rest of your application. The default is `false`. ```jsx render-no-edit () => { return ( <React.Fragment> <LoadingOverlay loadingTitle="isLoading is set to true" isLoading> <Card css={{ 'abyss-card-root': { height: 250, display: 'flex', justifyContent: 'center', alignItems: 'center', backgroundColor: '$gray4', }, }} > <Text> This text will be covered by the overlay when isLoading is set to true. </Text> </Card> </LoadingOverlay> <LoadingOverlay loadingTitle="isLoading set to false"> <Card css={{ 'abyss-card-root': { height: 250, display: 'flex', justifyContent: 'center', alignItems: 'center', backgroundColor: '$gray4', }, }} > <Text> isLoading is set to false, so the overlay will not be displayed </Text> </Card> </LoadingOverlay> </React.Fragment> ); }; ``` ## onClose Use the `onClose` prop to set a function that will be executed when the loading overlay is closed. ```jsx render-no-edit () => { const [isOpen, setIsOpen] = useState(true); const handleClose = () => { setIsOpen(false); console.log('Loading overlay closed!'); }; return ( <LoadingOverlay statusTitle="onClose Example" statusMessage="A message will be logged to the console when this overlay is closed." isLoading={false} isOpen={isOpen} onClose={handleClose} isDismissable > <Card css={{ 'abyss-card-root': { height: 200, display: 'flex', justifyContent: 'center', alignItems: 'center', backgroundColor: '$gray4', }, }} > <Button onClick={() => setIsOpen(true)}>Reopen Overlay</Button> </Card> </LoadingOverlay> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={LoadingOverlay} rows={[ { name: 'children', type: 'ReactNode | function', description: 'The contents that the LoadingOverlay will appear over when it is open', }, { name: 'model', type: 'string', description: 'Unique identifier used with useOverlay hook', }, { name: 'loadingTitle', type: 'string', description: 'Set the title that will display when the overlay is in the loading state ($isLoading is set to true)', }, { name: 'loadingMessage', type: 'string', description: 'Set the message that will display under the title when the overlay is in the loading state ($isLoading is set to true)', }, { name: 'statusTitle', type: 'string', description: 'Set the title that will display when loading is complete ($isLoading is set to false)', }, { name: 'statusMessage', type: 'string', description: 'Set the message that will display under the title when loading is complete ($isLoading is set to false)', }, { name: 'ariaLoadingLabel', type: 'string', description: 'Accessibility prop to label the loading spinner according to what it is loading', default: 'Loading', }, { name: 'statusIcon', type: "'info' | 'success' | 'error' | 'warning'", description: 'Set the icon that will be displayed when loading is complete ($isLoading is set to false)', }, { name: 'isOpen', type: 'boolean', description: 'Flag to check if the overlay is opened', }, { name: 'isLoading', type: 'boolean', description: 'Flag to check if the overlay is loading', }, { name: 'onClose', type: 'function', description: 'Callback fired every time the overlay is closed', }, { name: 'loadingIcon', type: 'ReactNode', description: 'Icon that will be displayed inside of the loading spinner', }, { name: 'width', type: 'string | number', description: 'The width of the loading dialog', }, { name: 'isDismissable', type: 'boolean', description: 'Flag to set whether or not the overlay is dismisable', }, { name: 'hideIcon', type: 'boolean', description: 'Flag to set whether or not to show the status icon', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={LoadingOverlay} rows={[ { name: 'loading-overlay-root', description: 'Root element', }, { name: 'loading-overlay-overlay', description: 'Overlay', }, { name: 'loading-overlay-dialog', description: 'Dialog', }, { name: 'loading-overlay-close-button', description: 'Close button', }, { name: 'loading-overlay-close-icon', description: 'Close icon', }, { name: 'loading-overlay-loading-body', description: 'Body container when loading', }, { name: 'loading-overlay-status-icon-wrapper', description: 'Wrapper for status icon', }, { name: 'loading-overlay-loading-content', description: 'Title and message displayed when loading', }, { name: 'loading-overlay-loading-title', description: 'Title when loading', }, { name: 'loading-overlay-loading-message', description: 'Message when loading', }, { name: 'loading-overlay-status-body', description: 'Body container when loaded', }, { name: 'loading-overlay-status-content', description: 'Title and message displayed when loaded', }, { name: 'loading-overlay-status-title', description: 'Title when loaded', }, { name: 'loading-overlay-status-message', description: 'Message when loaded', }, ]} /> ``` </Tab> <Tab label="Accessibility"> <h2>Simple LoadingOverlay</h2> A basic LoadingOverlay, when `isDismissable = false`, is used to indicate to the user that a process is occurring during which time they may not interact with any elements underneath the overlay. The overlay is coded as an [Alert](/web/ui/alert?tab=accessibility), meaning that most screen readers will announce the overlay once it renders. By default, the LoadingOverlay contains no interactive elements Adheres to the <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/alert/">Alert WAI-ARIA design pattern</ExitLink>. The <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/alert/examples/alert/">Alert Example</ExitLink> provided by W3.org demonstrates the Alert Pattern. ```jsx render-no-edit () => { const [isLoading, setIsLoading] = useState(false); const { setCountdownTime } = useCountdown({ onCompleted: () => { setIsLoading(false); }, }); return ( <LoadingOverlay loadingTitle="loadingTitle" loadingMessage="loadingMessage" ariaLoadingLabel="ariaLoadingLabel" isLoading={isLoading} > <Card css={{ 'abyss-card-root': { height: 250, display: 'flex', justifyContent: 'center', alignItems: 'center', backgroundColor: '$gray4', }, }} > <Button onClick={() => { setIsLoading(true); setCountdownTime(5000); }} > Open LoadingOverlay </Button> </Card> </LoadingOverlay> ); }; ``` <h2>LoadingOverlay Alert Dialog</h2> LoadingOverlay becomes an interactive alert dialog when `isDismissable = true`. The only interactions are to move focus through, or close the dialog window. This follows the <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/examples/alertdialog/">WAI-ARIA Alert Dialog Example</ExitLink> and has limited keyboard interaction to close the overlay using the Close button or Escape. ```jsx render-no-edit () => { const [isOpen, setIsOpen] = useState(false); return ( <LoadingOverlay statusTitle="statusTitle" statusMessage="statusMessage" ariaLoadingLabel="ariaLoadingLabel" onClose={() => setIsOpen(false)} isOpen={isOpen} isLoading={false} isDismissable > <Card css={{ 'abyss-card-root': { height: 250, display: 'flex', justifyContent: 'center', alignItems: 'center', backgroundColor: '$gray4', }, }} > <Button onClick={() => setIsOpen(true)}>Open LoadingOverlay</Button> </Card> </LoadingOverlay> ); }; ``` </Tab> --- id: loading-spinner-v2 category: Overlay title: V2LoadingSpinner description: Infinite loading spinner. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=11298-131 sourceIsTS: true subDirectory: LoadingSpinner/v2 --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="LoadingSpinner"></Docs.V2MigrationBanner> ``` ```jsx import { V2LoadingSpinner } from '@uhg-abyss/web/ui/LoadingSpinner'; ``` ## Overview The `V2LoadingSpinner` visually communicates that an operation such as data fetching, file downloading, or form submission is in progress, all without disrupting the user's current focus. The prop `isLoading` controls the visibility of the spinner, allowing it to be shown or hidden based on the loading state of your application; by default, this is set to `false`. It requires the `ariaLoadingLabel` prop to describe what is happening while the spinner is active, for example, "Submitting form", "Downloading files", "Content is loading", etc. Be as descriptive as possible. ```jsx <V2LoadingSpinner ariaLoadingLabel="Downloading" isLoading={isLoading} /> ``` ## Size and variant The V2LoadingSpinner component comes in three sizes: - `xs`: Compact size designed specifically for use within buttons - `lg`: Standard size for general use (default) - `xl`: Larger size for greater visibility The component offers two styling variants: - `primary`: Default styling for light backgrounds - `alt`: Alternative styling optimized for dark backgrounds ```jsx live () => { const [isLoading, setIsLoading] = useState(true); return ( <Layout.Stack space={20}> <Layout.Group space={20}> <V2LoadingSpinner size="xs" isLoading={isLoading} ariaLoadingLabel="Downloading files" /> <V2LoadingSpinner size="lg" isLoading={isLoading} ariaLoadingLabel="Retreiving profile" /> <V2LoadingSpinner size="xl" isLoading={isLoading} ariaLoadingLabel="Submitting form" /> </Layout.Group> <Box color="#333"> <Layout.Group space={20}> <V2LoadingSpinner size="xs" variant="alt" isLoading={isLoading} ariaLoadingLabel="Downloading files" /> <V2LoadingSpinner variant="alt" size="lg" isLoading={isLoading} ariaLoadingLabel="Retreiving profile" /> <V2LoadingSpinner size="xl" variant="alt" isLoading={isLoading} ariaLoadingLabel="Submitting form" /> </Layout.Group> </Box> </Layout.Stack> ); }; ``` ## Label Use the optional prop `label` to provide an additional description for your spinner. The `label` prop should be an object with: - `heading` - required, a short title or heading for the spinner - `headingLevel` - optional, a number from 0 to 5 indicating the heading level (default is 3). You can read more about heading levels in our [Heading component](/web/ui/heading/#offset). - `bodyText` - optional, a longer description or body text that provides more context about the loading state For spinners with a size of `xs`, text labels will not be displayed regardless of the provided `label` values. Note: The `ariaLoadingLabel` prop should match the `heading` value in the `label` prop to ensure accessibility compliance. ```jsx live () => { const [isLoading, setIsLoading] = useState(true); const toggleLoading = () => { setIsLoading(!isLoading); }; return ( <Layout.Group space={20}> <Box> <V2LoadingSpinner size="xl" isLoading={isLoading} ariaLoadingLabel="Loading Page" label={{ heading: 'Loading Page', headingLevel: 3, bodyText: 'User Profile', }} /> </Box> <Box color="#333"> <V2LoadingSpinner variant="alt" size="xl" isLoading={isLoading} ariaLoadingLabel="Loading Page" label={{ heading: 'Loading Page', headingLevel: 3, bodyText: 'User Profile', }} /> </Box> </Layout.Group> ); }; ``` ## Color Use the optional `color` prop to change the color of the spinner. ```jsx live () => { const [isLoading, setIsLoading] = useState(true); return ( <Layout.Group space={20}> <V2LoadingSpinner size="lg" isLoading={isLoading} ariaLoadingLabel="Loading page" color="$interactive1" /> </Layout.Group> ); }; ``` ## Button The Button component has V2LoadingSpinner integration. See the [V2Button](/web/ui/button-v2) documentation to learn more. ```jsx live () => { const [isLoading, setIsLoading] = useState(true); return ( <V2Button isLoading={isLoading} ariaLoadingLabel="Importing data"> Submit </V2Button> ); }; ``` ## Content wrapping and overflow Use the optional `width` prop to set a fixed width for the spinner. This is useful when you want to ensure that the spinner does not exceed a certain size, especially in responsive designs. By default, the spinner has a width of `fit-content`, meaning it will adjust its size based on the content and available space. ```jsx live () => { const [isLoading, setIsLoading] = useState(true); return ( <Layout.Group space={20}> <V2LoadingSpinner size="lg" isLoading={isLoading} ariaLoadingLabel="Downloading files" width="200px" label={{ heading: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.', headingLevel: 3, bodyText: 'Praesent eu vehicula nulla, eget sagittis mi. Praesent commodo fringilla erat, et rutrum nibh sodales vitae.', }} /> <V2LoadingSpinner size="xl" isLoading={isLoading} ariaLoadingLabel="Downloading files" width={400} label={{ heading: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.', headingLevel: 3, bodyText: 'Praesent eu vehicula nulla, eget sagittis mi. Praesent commodo fringilla erat, et rutrum nibh sodales vitae. Nunc non diam nec leo rhoncus rhoncus. Nullam dapibus ornare mi vel elementum. Integer ultricies pulvinar sapien ac varius. Sed a posuere odio. Duis iaculis quam sit amet consectetur finibus.', }} /> </Layout.Group> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2LoadingSpinner" propTypeName="V2LoadingSpinnerProps" /> ``` ```jsx render <Docs.V2ClassesTable title="V2Chip.Group" classes={[V2LoadingSpinnerClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> Following the requirements of WAI-ARIA, LoadingSpinner follows the requirements of 4.1.3: Status Messages. Status messages are defined by WCAG as messages that provide information on the success or results of a user action, but do not change the user's context (i.e., take focus). LoadingSpinner is programmed through the `ariaLoadingLabel` property, and has been tested using a screen reader to present a status message to assistive technology without receiving focus. Adheres to the <ExitLink href="https://www.w3.org/WAI/WCAG21/Understanding/status-messages.html">Status messages WAI-ARIA design pattern</ExitLink>. ```jsx live () => { const [isLoading, setIsLoading] = useState(true); return ( <Layout.Group space={20}> <V2LoadingSpinner size="lg" isLoading={isLoading} ariaLoadingLabel="Loading page" color="red" /> <V2LoadingSpinner size="lg" isLoading={isLoading} ariaLoadingLabel="Downloading files" width="200px" label={{ heading: 'Downloading', headingLevel: 3, bodyText: 'This may take a while.', }} /> <V2Button isLoading={isLoading} ariaLoadingLabel="Importing data"> Submit </V2Button> </Layout.Group> ); }; ``` Screen reader behavior when used within a `button`: JAWS suppresses announcement of button when `aria-busy="true"` - For most screen readers (NVDA, VoiceOver-Mac), the use of `aria-busy="true"` includes this state in the announcement of the button. - JAWS' implementation is to suppress announcement of the button until `aria-busy="false"` (or removed). - This is a known "feature" documented here (since May 16, 2018): <ExitLink href="https://www.tpgi.com/short-note-on-being-busy/">Short note on being busy - TPGi</ExitLink>. <h3> Reduced Motion </h3> For users who have `prefers-reduced-motion` set to `reduced`, the animation of the spinner is disabled. </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={V2LoadingSpinner} keys={['loadingSpinnerV2']} /> ``` </Tab> --- id: loading-spinner category: Overlay title: LoadingSpinner description: Infinite loading spinner. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=3697-25801 subDirectory: LoadingSpinner/v1 --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="LoadingSpinner"></Docs.V2MigrationBanner> ``` ```jsx import { LoadingSpinner } from '@uhg-abyss/web/ui/LoadingSpinner'; ``` ## Overview The LoadingSpinner requires the `ariaLoadingLabel` prop to describe what is happening while the spinner is active, for example, "Submitting form", "Downloading files", "Content is loading", etc. Be as descriptive as possible. ```jsx <LoadingSpinner ariaLoadingLabel="Downloading" isLoading={isLoading} /> ``` ## Variants LoadingSpinner comes in three sizes: `$lg`, `$md`, and `$sm`. The `$sm` variant is reserved solely for [use in Buttons](#button). There are two variants: `default` and `light`. The default value for `size` is `$md` and the default value for `variant` is `default`. ```jsx live () => { const [isLoading, setIsLoading] = useState(true); const toggleLoading = () => { setIsLoading(!isLoading); }; return ( <Layout.Stack space={20}> <Layout.Group space={20}> <LoadingSpinner size="$sm" isLoading={isLoading} ariaLoadingLabel="Downloading files" /> <LoadingSpinner isLoading={isLoading} ariaLoadingLabel="Importing data" /> <LoadingSpinner size="$lg" isLoading={isLoading} ariaLoadingLabel="Submitting form" /> </Layout.Group> <Box color="$primary1"> <Layout.Group space={20}> <LoadingSpinner size="$sm" variant="light" isLoading={isLoading} ariaLoadingLabel="Downloading files" /> <LoadingSpinner variant="light" isLoading={isLoading} ariaLoadingLabel="Importing data" /> <LoadingSpinner size="$lg" variant="light" isLoading={isLoading} ariaLoadingLabel="Submitting form" /> </Layout.Group> </Box> </Layout.Stack> ); }; ``` ## Children On size `$lg`, the LoadingSpinner can display a child element, most commonly an icon to further depict the action occuring while the spinner is active. See the Brandmark, IconSymbol, or IconBrand pages for options. ```jsx live () => { const [isLoading, setIsLoading] = useState(true); const toggleLoading = () => { setIsLoading(!isLoading); }; return ( <Layout.Group> <LoadingSpinner size="$lg" isLoading={isLoading} ariaLoadingLabel="Loading page" > <IconSymbol color="$loadingSpinnerPrimary1" icon="upload_file" size="35px" /> </LoadingSpinner> <Box color="$primary1"> <LoadingSpinner size="$lg" variant="light" isLoading={isLoading} ariaLoadingLabel="Downloading files" > <IconSymbol color="$white" icon="upload_file" size="35px" /> </LoadingSpinner> </Box> </Layout.Group> ); }; ``` ## Color Use `color` prop to change the color of the spinner. The default value of `color` is `null`. ```jsx live () => { const [isLoading, setIsLoading] = useState(true); const toggleLoading = () => { setIsLoading(!isLoading); }; return ( <LoadingSpinner size="$lg" isLoading={isLoading} ariaLoadingLabel="Loading page" color="$interactive1" > <IconSymbol color="$interactive1" icon="upload_file" size="35px" /> </LoadingSpinner> ); }; ``` ## Button The Button component has LoadingSpinner integration. See the [Button](/web/ui/button) documentation to learn more. ```jsx live () => { const [isLoading, setIsLoading] = useState(true); return ( <Layout.Group space={20}> <Layout.Stack space={20}> <Button isLoading={isLoading} ariaLoadingLabel="Importing data" onClick={() => setIsLoading(!isLoading)} > Submit </Button> </Layout.Stack> </Layout.Group> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={LoadingSpinner} rows={[ { name: 'children', type: 'node', description: 'The contents of the spinner component', }, { name: 'isLoading', type: 'boolean', description: 'Flag to show or hide the loading spinner. If true, spinner is visible', }, { name: 'size', type: 'number | string', description: 'Set the size of the spinner', }, { name: 'sizes', type: 'shape', description: 'Default sizes of the spinner', }, { name: 'variant', type: 'string', description: 'Set what color the spinner will be. `light` or `default`', }, { name: 'color', type: 'string', description: 'Set the color of the spinner', }, { name: 'ariaLoadingLabel', type: 'string', description: 'Text to describe what is happening while the loading spinner is active', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={LoadingSpinner} rows={[ { name: 'loading-spinner-root', description: 'Spinner root element', }, ]} /> ``` </Tab> <Tab label="Accessibility"> Following the requirements of WAI-ARIA, LoadingSpinner follows the requirements 4.1.3: Status Messages. Status messages are defined by WCAG as messages that provide information on the success or results of a user action, but do not change the users context (i.e. take focus). LoadingSpinner is programmed through the `ariaLoadingLabel` property, and has been tested using a screen reader to present a status message to assistive technology without receiving focus. Adheres to the <ExitLink href="https://www.w3.org/WAI/WCAG21/Understanding/status-messages.html">Status messages WAI-ARIA design pattern</ExitLink>. ```jsx live () => { const [isLoading, setIsLoading] = useState(true); const toggleLoading = () => { setIsLoading(!isLoading); }; return ( <LoadingSpinner size="$lg" isLoading={isLoading} ariaLoadingLabel="Downloading files" > <IconSymbol color="$primary1" icon="upload_file" size="35px" /> </LoadingSpinner> ); }; ``` Screen reader behavior: JAWS suppresses announcement of button when `aria-busy="true"` - For most screen readers (NVDA, VoiceOver-Mac), the use of `aria-busy="true"` includes this state in the announcement of the button. - JAWS' implementation is to suppress announcement of the button until `aria-busy="false"` (or removed). - This is a known "feature" documented here (since May 16, 2018): <ExitLink href="https://www.tpgi.com/short-note-on-being-busy/">Short note on being busy - TPGi</ExitLink>. </Tab> --- id: media-query category: Layout title: MediaQuery description: Used to layout UI elements conditionally --- <Tab label="Overview"> ```jsx import { MediaQuery } from '@uhg-abyss/web/ui/MediaQuery'; ``` ## Usage Used to conditionally display elements based on the window size. The condition is based on the `smallerThan` or `largerThan` props (or both of them at the same time). ```jsx live <React.Fragment> <div> An icon will appear to the right when the window size is at least extra large: <MediaQuery largerThan="$xl"> <IconSymbol icon="home" /> </MediaQuery> </div> <div> An icon will appear to the right when the window size is less than extra large: <MediaQuery smallerThan="$xl"> <IconSymbol icon="home" /> </MediaQuery> </div> <div> An icon will appear to the right when the window size is between large and extra large: <MediaQuery smallerThan="$xl" largerThan="$lg"> <IconSymbol icon="home" /> </MediaQuery> </div> </React.Fragment> ``` ## Smaller than Use the `smallerThan` prop to specify a width that the window must be smaller than for the contents inside the MediaQuery to display. ```jsx live <div> An icon will appear to the right when the window size is less than 1400 pixels: <MediaQuery smallerThan={1400}> <IconSymbol icon="home" /> </MediaQuery> </div> ``` ## Larger than Use the `largerThan` prop to specify a width that the window must be greater than or equal to for the contents inside the MediaQuery to display. ```jsx live <div> An icon will appear to the right when the window size is at least 700 pixels: <MediaQuery largerThan={700}> <IconSymbol icon="home" /> </MediaQuery> </div> ``` ## Preset breakpoints As an alternative to using hardcoded number / pixel values for `smallerThan` and `largerThan`, you can use preset breakpoints to ensure consistency across your app. (Breakpoint values are taken from the app's theme configuration.) Possible values are `$xs`, `$sm`, `$md`, `$lg`, and `$xl`. ```jsx live <div> An icon will appear to the right when the window size is at least the size of the $md breakpoint: <MediaQuery largerThan="$md"> <IconSymbol icon="home" /> </MediaQuery> </div> ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={MediaQuery} rows={[ { name: 'children', type: 'ReactNode', description: 'The element the group wraps', }, { name: 'smallerThan', type: 'number | string', description: 'Pixel amount the window width must be smaller than in order for the children to render', }, { name: 'largerThan', type: 'number | string', description: 'Pixel amount the window width must be greater than or equal to in order for the children to render', }, { name: 'breakpoints', type: 'shape', description: 'The breakpoints of MediaQuery component', }, ]} /> ``` </Tab> --- id: modal category: Overlay title: Modal description: Displays an overlay area at the center of the screen. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=0-1550 --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="Modal"></Docs.V2MigrationBanner> ``` ```jsx import { Modal } from '@uhg-abyss/web/ui/Modal'; ``` ```jsx sandbox { component: 'Modal', inputs: [ { prop: 'children', type: 'string', }, { prop: 'title', type: 'string', }, { prop: 'size', type: 'string', }, ], } () => { const [isOpen, setIsOpen] = useState(false); return ( <React.Fragment> <Modal title="Enter title here" isOpen={isOpen} onClose={() => setIsOpen(false)} > <Modal.Section>Press escape to close the modal</Modal.Section> </Modal> <Button onClick={() => setIsOpen(true)} aria-haspopup="dialog"> Toggle Modal </Button> </React.Fragment> ); } ``` ## useOverlay Using the `useOverlay` hook lets the DOM handle form data and the overlays state. To utilize the [useOverlay](/web/hooks/use-overlay) hook the root/parent must be wrapped with the [OverlayProvider](/web/ui/overlay-provider). ```jsx live () => { const modal = useOverlay('modal-form'); const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; const menuItems = [ { title: 'Print', onClick: () => { console.log('Print'); }, icon: <IconSymbol icon="print" />, }, { title: 'Save As...', onClick: () => { console.log('Save As...'); }, icon: <IconSymbol icon="save" />, }, ]; return ( <React.Fragment> <Button onClick={() => modal.open()} aria-haspopup="dialog"> Toggle Modal </Button> <FormProvider state={form} onSubmit={onSubmit}> <Modal title="Register" model="modal-form"> <Modal.Section> <Grid> <Grid.Col span={6}> <TextInput label="First Name" model="first-name" validators={{ required: true }} /> </Grid.Col> <Grid.Col span={6}> <TextInput label="Last Name" model="last-name" validators={{ required: true }} /> </Grid.Col> <Grid.Col span={6}> <DateInput label="Date" model="date" validators={{ required: true }} /> </Grid.Col> <Grid.Col span={6}> <TimeInput label="Time" model="time" validators={{ required: true }} /> </Grid.Col> <Grid.Col span={12}> <TextInput label="Password" type="password" model="password" validators={{ required: true }} /> </Grid.Col> <Grid.Col span={12}> <SelectInput label="Your favorite framework/library" placeholder="Pick one" model="framework" isClearable isSearchable options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} validators={{ required: true }} /> </Grid.Col> <Grid.Col span={12}> <Layout.Group alignItems="top"> <Checkbox label="I agree to terms and conditions" model="terms-condition" validators={{ required: true }} /> <Popover title="Term Conditions" content="Description would go here detailing the terms and conditions." /> </Layout.Group> </Grid.Col> <Grid.Col span={12}> <DropdownMenu outline label="Download Terms" before={<IconSymbol icon="download" />} after={<IconSymbol icon="keyboard_arrow_down" />} menuItems={menuItems} /> </Grid.Col> </Grid> </Modal.Section> <Modal.Section> <Layout.Group alignLayout="right"> <Button variant="outline" onClick={() => modal.close()}> Cancel </Button> <Tooltip content="Use this button to submit the form."> <Button onClick={() => { form.handleSubmit(onSubmit)(); if (form.formState.isValid) { modal.close(); } }} > Submit </Button> </Tooltip> </Layout.Group> </Modal.Section> </Modal> </FormProvider> </React.Fragment> ); }; ``` ## useState Using the `useState` hook to set the open state of the modal. ```jsx live () => { const [isOpen, setIsOpen] = useState(false); const [value, setValue] = useState('11/01/2023'); const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( <React.Fragment> <Button onClick={() => setIsOpen(true)} aria-haspopup="dialog"> Toggle Modal </Button> <FormProvider state={form} onSubmit={onSubmit}> <Modal title="Register" isOpen={isOpen} onClose={() => setIsOpen(false)} > <Modal.Section> <Grid> <Grid.Col span={6}> <TextInput label="First Name" model="firstName" /> </Grid.Col> <Grid.Col span={6}> <TextInput label="Last Name" model="lastName" /> </Grid.Col> <Grid.Col span={12}> <TextInput label="Email" type="email" model="email" /> </Grid.Col> <Grid.Col span={12}> <TextInput label="Password" type="password" model="password" /> </Grid.Col> <Grid.Col span={12}> <DateInput label="DateInput Sandbox" value={value} onChange={setValue} /> </Grid.Col> <Grid.Col span={12}> <Checkbox label="I agree to terms and conditions" model="tc" /> </Grid.Col> </Grid> </Modal.Section> <Modal.Section> <Layout.Group alignLayout="right"> <Button variant="outline" onClick={() => setIsOpen(false)}> Cancel </Button> <Tooltip content="Use this button to submit the form."> <Button onClick={() => { form.handleSubmit(onSubmit)(); if (form.formState.isValid) { setIsOpen(false); } }} > Submit </Button> </Tooltip> </Layout.Group> </Modal.Section> </Modal> </FormProvider> </React.Fragment> ); }; ``` ## Title Use the `title` prop to set the title of the modal. For accessibility purposes a title is required. Please provide a title that accurately describes the content of the modal so on open a screen reader can provide this description to the user. If you'd like to hide the title from being displayed you can use the `hideTitle` prop found [below](#hide-title). ```jsx live () => { const modal = useOverlay('title-modal'); return ( <React.Fragment> <Button onClick={() => modal.open()} aria-haspopup="dialog"> Toggle Modal </Button> <Modal title="Custom Title" model="title-modal"> <Modal.Section>Custom Title</Modal.Section> </Modal> </React.Fragment> ); }; ``` ## Hide title Use the `hideTitle` prop to hide the title from displaying with the modal. ```jsx live () => { const modal = useOverlay('hide-title-modal'); return ( <React.Fragment> <Button onClick={() => modal.open()} aria-haspopup="dialog"> Toggle Modal </Button> <Modal title="Custom Title" model="hide-title-modal" hideTitle> <Modal.Section>Custom Title</Modal.Section> </Modal> </React.Fragment> ); }; ``` ## Passing data Use the `getState` method retrieve the state of the modal. Structure: `{ isOpen: Boolean, data: Object }`. Pass data into the open/toggle methods to use in the modal. ```jsx live () => { const modal = useOverlay('data-modal'); const { data } = modal.getState(); return ( <React.Fragment> <Button onClick={() => modal.open({ firstName: 'John', lastName: 'Doe' })} aria-haspopup="dialog" > Toggle Modal </Button> <Modal title="Passing Data to Modal" model="data-modal"> <Modal.Section> <p>First Name: {data && data.firstName}</p> <p>Last Name: {data && data.lastName}</p> </Modal.Section> </Modal> </React.Fragment> ); }; ``` ## Size Use the `size` prop to set the width of the modal. ```jsx live () => { const [isOpen, setIsOpen] = useState(false); const [size, setSize] = useState('lg'); const handleClick = (size) => { setIsOpen(true); setSize(size); }; return ( <React.Fragment> <Layout.Group> <Button onClick={() => handleClick('lg')} aria-haspopup="dialog"> Large (Default) </Button> <Button onClick={() => handleClick('md')} aria-haspopup="dialog"> Medium </Button> <Button onClick={() => handleClick('sm')} aria-haspopup="dialog"> Small </Button> <Button onClick={() => handleClick('full')} aria-haspopup="dialog"> Full </Button> </Layout.Group> <Modal title={`Modal Size: ${size}`} isOpen={isOpen} onClose={() => setIsOpen(false)} size={size} > <Modal.Section>Press escape to close the modal</Modal.Section> </Modal> </React.Fragment> ); }; ``` ## Title align Use the `titleAlign` prop to align the position of the title. ```jsx live () => { const form = useForm(); const modal = useOverlay('title-aligment'); const [align, setAlign] = useState('left'); const onSubmit = (data) => { console.log('data', data); }; return ( <React.Fragment> <Layout.Group> <Button onClick={() => { modal.open(); setAlign('left'); }} aria-haspopup="dialog" > Left </Button> <Button onClick={() => { modal.open(); setAlign('center'); }} aria-haspopup="dialog" > Center </Button> <Button onClick={() => { modal.open(); setAlign('right'); }} aria-haspopup="dialog" > Right </Button> </Layout.Group> <FormProvider state={form} onSubmit={onSubmit}> <Modal title="Title Alignment" titleAlign={align} model="title-aligment" > <Modal.Section> <Grid> <Grid.Col span={6}> <TextInput label="First Name" model="firstName" /> </Grid.Col> <Grid.Col span={6}> <TextInput label="Last Name" model="LastName" /> </Grid.Col> <Grid.Col span={12}> <TextInput label="Email" type="email" model="email" /> </Grid.Col> <Grid.Col span={12}> <TextInput label="Password" type="password" model="password" /> </Grid.Col> <Grid.Col span={12}> <Checkbox label="I agree to terms and conditions" model="tc" /> </Grid.Col> </Grid> </Modal.Section> <Modal.Section> <Layout.Group alignLayout="right"> <Button variant="outline" onClick={() => modal.close()}> Cancel </Button> <Button type="submit">Submit</Button> </Layout.Group> </Modal.Section> </Modal> </FormProvider> </React.Fragment> ); }; ``` ## Overflow Overflow is handled within the content of the modal. The title will remain static. The `scrollableFocus` prop can be passed in to allow the scrollable body content to be focusable. ```jsx live () => { const modal = useOverlay('overflow-modal'); return ( <React.Fragment> <Button onClick={() => modal.open()} aria-haspopup="dialog"> Toggle Modal </Button> <Modal title="Overflow" model="overflow-modal" scrollableFocus> <Modal.Section> {Array.from(Array(50).keys()).map((item) => { return ( <p key={item} style={{ marginBottom: 65 }}> Overflow Example - Scroll </p> ); })} </Modal.Section> </Modal> </React.Fragment> ); }; ``` ## Modal footer Use the `Modal.Footer` to add a footer container to a modal. ```jsx live () => { const modal = useOverlay('modal-footer'); return ( <React.Fragment> <Button onClick={() => modal.open()} aria-haspopup="dialog"> Toggle Modal </Button> <Modal title="Modal With Footer " model="modal-footer" footer={ <Modal.Section> <Layout.Group alignLayout="right"> <Button onClick={() => modal.close()}>Cancel</Button> </Layout.Group> </Modal.Section> } > <Modal.Section> {Array.from(Array(30).keys()).map((item) => { return ( <p key={item} style={{ marginBottom: 65 }}> modal footer with cancel button </p> ); })} </Modal.Section> </Modal> </React.Fragment> ); }; ``` ## closeOnClickOutside Use the `closeOnClickOutside` to prevent closing the modal on background clicks. Modals using this prop can still be closed with the close button or through use of state. ```jsx live () => { const modal = useOverlay('closeOnClickOutside-modal'); return ( <React.Fragment> <Button onClick={() => modal.open()} aria-haspopup="dialog"> Toggle Modal </Button> <Modal closeOnClickOutside={false} title="No Close on Outside Click" model="closeOnClickOutside-modal" > <Modal.Section>No Close on Outside Click</Modal.Section> </Modal> </React.Fragment> ); }; ``` ## closeOnEscPress Use the `closeOnEscPress` to prevent closing the modal on Esc key. Modals using this prop can still be closed with the close button or through use of state. Accessibility Notice: The ability to close or dismiss modals and dialogs with the escape key is an absolutely fundamental requirement for accessible keyboard navigation. As such, this prop should ONLY be used temporarily when programmatically necessary, such as waiting for search results to load or for an API call to return. If the process hangs or takes more than a few seconds, then this prop should be removed so users can choose to dismiss the modal. ```jsx live () => { const modal = useOverlay('closeOnEscPress-modal'); return ( <React.Fragment> <Button onClick={() => modal.open()} aria-haspopup="dialog"> Toggle Modal </Button> <Modal closeOnEscPress={false} title="No Close on Escape Press" model="closeOnEscPress-modal" > <Modal.Section>No Close on Escape Press</Modal.Section> </Modal> </React.Fragment> ); }; ``` ## Customization ```jsx live () => { const modal = useOverlay('customization'); return ( <React.Fragment> <Button onClick={() => modal.open()} aria-haspopup="dialog"> Toggle Modal </Button> <Modal title="Customize Modal To Fit Your Design Needs" titleAlign="center" model="customization" css={{ 'abyss-modal-header-container': { marginTop: '$md' }, }} > <div style={{ border: '7px solid white', background: 'white', borderRadius: '50%', position: 'absolute', top: '-2%', left: '50%', transform: 'translate(-50%, -50%)', }} > <IconBrand icon="desktop" size="xl" /> </div> <Modal.Section> <p> Nulla a hendrerit leo. Morbi ac suscipit nunc. Suspendisse cursus hendrerit magna quis euismod. Integer rhoncus, nulla in maximus efficitur, felis felis laoreet quam, ut tincidunt ex est eu nulla. Curabitur pharetra vel elit eu egestas. Donec consectetur rhoncus felis, efficitur tristique erat ultrices et. Proin at ipsum elit. Donec mauris sem, cursus a velit eu, hendrerit rhoncus mi. Ut quis sem lacinia, sodales nulla vel, feugiat odio. </p> </Modal.Section> <Modal.Section> <Layout.Stack alignLayout="center" alignItems="center"> <Button onClick={() => modal.close()}>Tell Me More</Button> <Link onClick={() => modal.close()}>Skip The Tour</Link> </Layout.Stack> </Modal.Section> </Modal> </React.Fragment> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={Modal} rows={[ { name: 'children', type: 'node', description: 'The contents of the Modal component', }, { name: 'footer', type: 'node', description: 'The contents of the Modal footer', }, { name: 'title', type: 'string', description: 'Set the title of the modal', }, { name: 'ariaLabel', type: 'string', description: 'Set the ariaLabel of modal', }, { name: 'model', type: 'string', description: 'Unique identifier used for FormProvider', }, { name: 'isOpen', type: 'boolean', description: 'Flag to check if modal is opened', }, { name: 'onClose', type: 'function', description: 'Callback fired every time modal is closed', }, { name: 'size', type: 'number | string', description: 'Size of modal', }, { name: 'titleAlign', type: 'string', description: 'Set the alignment of the title', }, { name: 'hideClose', type: 'boolean', description: 'set to true to hide close button on modal', }, { name: 'closeOnClickOutside', type: 'boolean', description: 'set to false to stop modal from closing on background click', }, { name: 'closeOnEscPress', type: 'boolean', description: 'set to false to stop modal from closing on escape key press', }, { name: 'scrollableFocus', type: 'boolean', description: 'set to true to allow the overflowed div to be focusable and scrollable with keys', }, { name: 'ref', type: 'object', description: 'ref of modal body container', }, { name: 'sizes', type: 'number | string', description: 'The sizes of the Modal component', }, { name: 'hideTitle', type: 'boolean', description: 'If true , it hides the title', }, { name: 'headerAction', type: 'ReactNode', description: 'Should be utilized in cases where a title is not provided and a component that includes a focusable element needs to be supplied to the header portion of the Modal. This element will receive initial focus rather than the close button', }, ]} /> ``` ```jsx render <Docs.PropsTable of={Modal.Section} rows={[ { name: 'children', type: 'ReactNode', description: 'The contents of the Modal Section component', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Modal} rows={[ { name: 'modal-root', description: 'Modal root element', }, { name: 'modal-overlay', description: 'Modal overlay element', }, { name: 'modal-content-container', description: 'Modal content container', }, { name: 'modal-header-container', description: 'Modal header container', }, { name: 'modal-header-title', description: 'Modal title element', }, { name: 'modal-body', description: 'Modal body element', }, { name: 'modal-footer', description: 'Modal footer element', }, { name: 'modal-close-button', description: 'Modal close button element', }, { name: 'modal-close-icon', description: 'Modal close icon element', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Modal.Section} rows={[ { name: 'modal-section-root', description: 'Modal Section root element', }, ]} /> ``` </Tab> <Tab label="Accessibility"> Adheres to the <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/">Accordion WAI-ARIA design pattern</ExitLink>. <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/dialog/">Example of Dialog-Modal provided on WAI-ARIA website</ExitLink>. ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Esc', description: 'Closes the dialog.', }, { name: 'Tab', description: 'Moves focus to the next interactive element within the dialog. Once the last interactive element in the dialog is reached, pressing Tab again moves focus to the first interactive element within the dialog.', }, { name: 'Shift + Tab', description: 'Moves focus to the previous interactive element within the dialog. Once the first interactive element in the dialog is reached, pressing Shift + Tab again moves focus to the last interactive element within the dialog.', }, ]} /> ``` <h3>Modal Accessible Example</h3> ```jsx live () => { const modal = useOverlay('customization'); return ( <React.Fragment> <Button onClick={() => modal.open()} aria-haspopup="dialog"> Open modal </Button> <Modal title="Exciting modal examples you too can use" titleAlign="center" model="customization" css={{ 'abyss-modal-header-container': { marginTop: '$md' }, }} > <div style={{ border: '7px solid white', background: 'white', borderRadius: '50%', position: 'absolute', top: '-2%', left: '50%', transform: 'translate(-50%, -50%)', }} > <IconBrand icon="desktop" size="xl" /> </div> <Modal.Section> <p>Looking for an exciting new modal dialog?</p> <p>One that's also fully accessible?</p> <p>You've come to the right place</p> </Modal.Section> <Modal.Section> <Layout.Stack alignLayout="center" alignItems="center"> <Button onClick={() => modal.close()}>Tell Me More</Button> <Link onClick={() => modal.close()}> Nah! I want to code my own </Link> </Layout.Stack> </Modal.Section> </Modal> </React.Fragment> ); }; ``` <h3>Dialog Content</h3> The content included on the dialog must be accessible. ```jsx live () => { const modal = useOverlay('accessible-modal'); return ( <> <Button onClick={() => modal.open()} aria-haspopup="dialog"> Toggle Modal </Button> <Modal title="Accessible Modal" model="accessible-modal"> <Modal.Section> <Button>Button is accessible in modal</Button> </Modal.Section> </Modal> </> ); }; ``` <h3>Triggering Elements</h3> Use the aria-haspopup attribute on buttons or other triggering elements that open content like dialogs, listboxes, trees, menus, grids, etc. Use a corresponding value that indicates what kind of popup will be displayed when the trigger element is activated. In turn, the element that pops up must be of the role indicated. For example use aria-haspop="dialog" on buttons that open modal dialogs. Be sure to include role="dialog" on the containing element of the dialog itself, too. See the docs on 'haspop' for more details:https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup aria-haspopup - Accessibility | MDN The aria-haspopup attribute indicates the availability and type of interactive popup element that can be triggered by the element on which the attribute is set. <h3>Esc Override</h3> Use the `closeOnEscPress` to prevent closing the modal on Esc key. Modals using this prop can still be closed with the close button or through use of state. Accessibility Notice: The ability to close or dismiss modals and dialogs with the escape key is an absolutely fundamental requirement for accessible keyboard navigation. As such, this prop should ONLY be used temporarily when programmatically necessary, such as waiting for search results to load or for an API call to return. If the process hangs or takes more than a few seconds, then this prop should be removed so users can choose to dismiss the modal. ```jsx live () => { const modal = useOverlay('closeOnEscPress-modal'); return ( <React.Fragment> <Button onClick={() => modal.open()} aria-haspopup="dialog"> Toggle Modal </Button> <Modal closeOnEscPress={false} title="No Close on Escape Press" model="closeOnEscPress-modal" > <Modal.Section>No Close on Escape Press</Modal.Section> </Modal> </React.Fragment> ); }; ``` <h2>Notes of Issues</h2> - Overflow do not allow scrolling of contents using the keyboard alone - They do not have any focusable elements (links, fields) so keyboard focus is not set to the scrolling div region <h2>Possible Workarounds</h2> - Add any focusable element at top of content, possibly using "top" or other element as start of section and "back to top" to scroll back to it (and provide another focusable element to ensure keyboard scrolling) </Tab> --- id: modal-dialog-v2 category: Overlay title: V2ModalDialog description: Displays an overlay area at the center of the screen. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=9281-19799 subDirectory: ModalDialog sourceIsTS: true --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="Modal"></Docs.V2MigrationBanner> ``` ```jsx import { V2ModalDialog } from '@uhg-abyss/web/ui/ModalDialog'; ``` ```jsx sandbox { component: 'V2ModalDialog', inputs: [ { prop: 'children', type: 'string', }, { prop: 'size', type: 'select', options: [ { label: '$sm', value: '$sm' }, { label: '$md', value: '$md' }, { label: 'custom', value: '100%' }, { label: 'Fullscreen', value: 'fullscreen' }, ], }, { prop: 'closeOnClickOutside', type: 'boolean', }, ], } () => { const [isOpen, setIsOpen] = useState(false); return ( <React.Fragment> <V2ModalDialog size="$md" header="Modal dialog header" isOpen={isOpen} onClose={() => setIsOpen(false)} closeOnClickOutside > Press escape to close the Modal </V2ModalDialog> <V2Button onClick={() => setIsOpen(true)} aria-haspopup="dialog"> Open Modal Dialog </V2Button> </React.Fragment> ); }; ``` ## Opening the ModalDialog There are two methods of controlling the open state of a V2ModalDialog: by using the `useOverlay` hook or by using the `isOpen` prop. ### useOverlay The [useOverlay hook](/web/hooks/use-overlay) returns an object containing various methods used to control the state of the modal. Each modal must be assigned a unique `model` prop and wrapped in an [OverlayProvider](/web/ui/overlay-provider). Note: If you're encountering issues ensure the modal is properly wrapped in an `OverlayProvider` / refer to the docs perspective pages for troubleshooting. ```jsx live () => { const modal = useOverlay('modal-form'); const form = useFormV2(); const onSubmit = (data) => { console.log('data', data); }; const footer = ( <Layout.Group> <V2Button onClick={() => { form.handleSubmit(onSubmit)(); if (form.formState.isValid) { modal.close(); } }} > Submit </V2Button> <V2Button onClick={() => { modal.close(); }} variant="outline" > Close </V2Button> </Layout.Group> ); return ( <React.Fragment> <V2Button onClick={() => modal.open()} aria-haspopup="dialog"> Toggle Modal Dialog </V2Button> <V2FormProvider state={form} onSubmit={onSubmit}> <V2ModalDialog header="Register" model="modal-form" onClose={() => { console.log('Modal closed'); }} footer={footer} > <Grid> <Grid.Col span={6}> <V2TextInput label="First Name" model="first-name" validators={{ required: true }} /> </Grid.Col> <Grid.Col span={6}> <V2TextInput label="Last Name" model="last-name" validators={{ required: true }} /> </Grid.Col> <Grid.Col span={12}> <V2TextInput label="Email" type="email" model="email" isClearable validators={{ required: true }} /> </Grid.Col> <Grid.Col span={12}> <V2SelectInput label="Country" model="country" isClearable options={[ { value: 'canada', label: 'Canada' }, { value: 'usa', label: 'USA' }, { value: 'mexico', label: 'Mexico' }, { value: 'uk', label: 'United Kingdom' }, { value: 'france', label: 'France' }, { value: 'germany', label: 'Germany' }, { value: 'japan', label: 'Japan' }, { value: 'australia', label: 'Australia' }, { value: 'brazil', label: 'Brazil' }, { value: 'india', label: 'India' }, ]} validators={{ required: true }} /> </Grid.Col> <Grid.Col span={12}> <V2TextInput label="Password" type="password" model="password" isClearable validators={{ required: true }} /> </Grid.Col> <Grid.Col> <V2Checkbox label="I agree to terms and conditions" model="terms-conditions" validators={{ required: true }} /> </Grid.Col> </Grid> </V2ModalDialog> </V2FormProvider> </React.Fragment> ); }; ``` ### useState The open state of the V2ModalDialog can also be controlled with the `isOpen` prop in conjunction with React's `useState` hook. ```jsx live () => { const [isOpen, setIsOpen] = useState(false); const form = useFormV2(); const onSubmit = (data) => { console.log('data', data); }; const footer = ( <Layout.Group> <V2Button onClick={() => { form.handleSubmit(onSubmit)(); if (form.formState.isValid) { setIsOpen(false); } }} > Submit </V2Button> <V2Button onClick={() => { setIsOpen(false); }} variant="outline" > Close </V2Button> </Layout.Group> ); return ( <React.Fragment> <V2Button onClick={() => setIsOpen(true)} aria-haspopup="dialog"> Open Modal Dialog </V2Button> <V2FormProvider state={form} onSubmit={onSubmit}> <V2ModalDialog header="Register" isOpen={isOpen} onClose={() => setIsOpen(false)} footer={footer} > <Grid> <Grid.Col span={6}> <V2TextInput label="First Name" model="first-name" validators={{ required: true }} /> </Grid.Col> <Grid.Col span={6}> <V2TextInput label="Last Name" model="last-name" validators={{ required: true }} /> </Grid.Col> <Grid.Col span={12}> <V2TextInput label="Email" type="email" model="email" isClearable validators={{ required: true }} /> </Grid.Col> <Grid.Col span={12}> <V2SelectInput label="Country" model="country" isClearable options={[ { value: 'canada', label: 'Canada' }, { value: 'usa', label: 'USA' }, { value: 'mexico', label: 'Mexico' }, { value: 'uk', label: 'United Kingdom' }, { value: 'france', label: 'France' }, { value: 'germany', label: 'Germany' }, { value: 'japan', label: 'Japan' }, { value: 'australia', label: 'Australia' }, { value: 'brazil', label: 'Brazil' }, { value: 'india', label: 'India' }, ]} validators={{ required: true }} /> </Grid.Col> <Grid.Col span={12}> <V2TextInput label="Password" type="password" model="password" isClearable validators={{ required: true }} /> </Grid.Col> <Grid.Col span={5}> <V2Checkbox label="I agree to terms and conditions" model="terms-conditions" validators={{ required: true }} /> </Grid.Col> </Grid> </V2ModalDialog> </V2FormProvider> </React.Fragment> ); }; ``` ## Header Use the `header` prop to set the header of the modal. This prop is optional but strongly recommended. It accepts a React node, and is typically a string representing the title of the modal. If not using `header`, please use `ariaLabel` to provide a title and keep the component accessible. ```jsx live () => { const [isHeaderModalOpen, setHeaderModalOpen] = useState(false); const [isNoHeaderModalOpen, setNoHeaderModalOpen] = useState(false); const [isCustomHeaderModalOpen, setCustomHeaderModalOpen] = useState(false); const sharedText = 'Lorem ipsum odor amet, consectetuer ultricey elit. Pretium rhoncus non ultricies arcu ultricies luctus montes. Consequat nostra risus proin netus condimentum cursus. Donec tempor orci aliquet, primis feugiat ad leo ullamcorper malesuada. Efficitur mollis non tristique himenaeos iaculis. Fusce viverra pellentesque sit iaculis porttitor vulputate. Aliquam pretium faucibus inceptos per porta habitasse. Ipsum praesent auctor fames taciti tortor. Venenatis aenean blandit tellus neque penatibus laoreet metus lorem eleifend. '; const customHeader = ( <React.Fragment> <span style={{ display: 'flex', alignItems: 'center', justifyContent: 'center', gap: '8px', }} > <IconSymbol color="$primary1" icon="home" size="28px" /> Custom Header </span> </React.Fragment> ); return ( <React.Fragment> <V2ModalDialog header={'Header'} isOpen={isHeaderModalOpen} onClose={() => setHeaderModalOpen(false)} > {sharedText} </V2ModalDialog> <V2ModalDialog header={customHeader} isOpen={isCustomHeaderModalOpen} onClose={() => setCustomHeaderModalOpen(false)} > {sharedText} </V2ModalDialog> <V2ModalDialog isOpen={isNoHeaderModalOpen} onClose={() => setNoHeaderModalOpen(false)} > {sharedText} </V2ModalDialog> <Layout.Group> <V2Button onClick={() => setHeaderModalOpen(true)} aria-haspopup="dialog" > Header </V2Button> <V2Button onClick={() => setCustomHeaderModalOpen(true)} aria-haspopup="dialog" > Custom Header </V2Button> <V2Button onClick={() => setNoHeaderModalOpen(true)} aria-haspopup="dialog" > No Header </V2Button> </Layout.Group> </React.Fragment> ); }; ``` ## Footer Use the `footer` prop to add a footer to the drawer. It accepts a React node, typically one or two buttons. ```jsx live () => { const modal = useOverlay('modal-dialog-footer'); const footer = ( <V2Button onClick={() => { modal.close(); }} > Close </V2Button> ); return ( <React.Fragment> <V2Button onClick={() => modal.open()} aria-haspopup="dialog"> Open Modal Dialog </V2Button> <V2ModalDialog header="Modal Dialog with footer" model="modal-dialog-footer" footer={footer} > Lorem ipsum odor amet, consectetuer adipiscing elit. Pretium rhoncus non ultricies arcu ultricies luctus montes. Consequat nostra risus proin netus condimentum cursus. Donec tempor orci aliquet, primis feugiat ad leo ullamcorper malesuada. Efficitur mollis non tristique himenaeos iaculis. Fusce viverra pellentesque sit iaculis porttitor vulputate. Aliquam pretium faucibus inceptos per porta habitasse. Ipsum praesent auctor fames taciti tortor. Venenatis aenean blandit tellus neque penatibus laoreet metus lorem eleifend. </V2ModalDialog> </React.Fragment> ); }; ``` ## Passing data External data can be passed into the modal dialog when using the `useOverlay` hook. The `open` and `toggle` methods returned by the hook accept an object of the following type: ```ts { isOpen?: boolean; data?: object; } ``` The `getState` method retrieves the state of the modal dialog as an object of the same type. ```jsx live () => { const StateOutput = styled('pre', { marginTop: '8px', }); const modal = useOverlay('data-modal'); const { isOpen, data } = modal.getState(); return ( <React.Fragment> <V2Button onClick={() => modal.open({ firstName: 'John', lastName: 'Doe' })} aria-haspopup="dialog" > Open Modal Dialog </V2Button> <StateOutput>{JSON.stringify({ isOpen, data }, null, 2)}</StateOutput> <V2ModalDialog header="Passing data" model="data-modal"> <p>First Name: {data && data.firstName}</p> <p>Last Name: {data && data.lastName}</p> </V2ModalDialog> </React.Fragment> ); }; ``` ## Size Use the `size` prop to set the width of the modal dialog. There are three preset values: - `'$sm'`, with a max width of 348px; - `'$md'`, with a max width of 720px; - `'fullscreen'`, which takes up the full viewport width and height. The default value is `'$md'`. It is also possible to provide a custom size by providing a string or a number to the `size` prop. ```jsx live () => { const [isOpen, setIsOpen] = useState(false); const [size, setSize] = useState('$md'); const handleClick = (size) => { setIsOpen(true); setSize(size); }; return ( <React.Fragment> <Layout.Group> <V2Button onClick={() => handleClick('$md')} aria-haspopup="dialog"> Medium </V2Button> <V2Button onClick={() => handleClick('$sm')} aria-haspopup="dialog"> Small </V2Button> <V2Button onClick={() => handleClick('fullscreen')} aria-haspopup="dialog" > Fullscreen </V2Button> <V2Button onClick={() => handleClick(550)} aria-haspopup="dialog"> Custom </V2Button> </Layout.Group> <V2ModalDialog header={`Modal Dialog size: ${ typeof size === 'string' ? size : 'custom' }`} isOpen={isOpen} onClose={() => setIsOpen(false)} size={size} > Lorem ipsum odor amet, consectetuer adipiscing elit. Odio nascetur pellentesque purus, convallis euismod magnis. Netus commodo malesuada tempor nullam consectetur sem. Netus posuere accumsan finibus imperdiet nulla; dis aptent felis. Quisque mi sociosqu massa ullamcorper magnis in adipiscing. Blandit vel conubia senectus, senectus quis fermentum facilisis varius. Ut porta ut himenaeos ultrices a ligula placerat mauris. Turpis risus mus maecenas imperdiet posuere. Amet justo eget finibus vitae proin turpis curae. Vel pharetra etiam mi, faucibus suspendisse cras senectus. </V2ModalDialog> </React.Fragment> ); }; ``` ## Overflow Overflow is handled within the content of the modal dialog. The header and footer, if present, will remain fixed. ```jsx live () => { const modal = useOverlay('overflow-modal'); const footer = ( <V2Button onClick={() => { modal.close(); }} > Close </V2Button> ); return ( <React.Fragment> <V2Button onClick={() => modal.open()} aria-haspopup="dialog"> Open Modal Dialog </V2Button> <V2ModalDialog header="Overflow" model="overflow-modal" footer={footer}> Lorem ipsum odor amet, consectetuer adipiscing elit. Class dictumst vehicula nascetur enim fringilla nascetur vivamus. Posuere volutpat felis suspendisse laoreet eu bibendum rutrum consectetur. Hac maximus cubilia euismod arcu netus potenti. Facilisis commodo torquent venenatis massa potenti et cras. Morbi semper vehicula conubia convallis lorem ante lacinia taciti feugiat. Pretium donec quis at praesent faucibus velit est. Lacinia torquent faucibus vehicula ut congue maecenas. <br /> Pharetra penatibus urna phasellus metus suscipit. Tortor porttitor quam inceptos accumsan nam, nibh semper ridiculus semper. Nullam ornare hac rhoncus viverra ipsum leo sollicitudin maximus sollicitudin. Platea quisque nulla convallis at porta lacus litora! Lacinia molestie dignissim ullamcorper, nostra non molestie sagittis id maximus. Ridiculus libero eleifend tincidunt phasellus elementum posuere suspendisse nisl mus. Dapibus felis ex nisl at ut, auctor sed nullam. Dis maximus molestie amet tincidunt fermentum vulputate interdum. <br /> Sollicitudin potenti mollis platea platea sed felis iaculis. Ornare mauris nulla eu efficitur dis euismod dui hendrerit. Facilisi ridiculus nibh fermentum vitae nisi accumsan aenean. Ornare vulputate cursus felis litora netus luctus. Sapien justo varius sit feugiat auctor. Suspendisse dolor aliquet pulvinar sit nullam pulvinar justo sollicitudin. Non finibus proin suscipit blandit leo magna morbi facilisis. <br /> Varius nostra dis sociosqu lacus elementum nam malesuada velit. Turpis leo eu dis nulla blandit vulputate pretium massa. Non potenti est scelerisque facilisis diam dui placerat inceptos maximus. Ligula natoque egestas pellentesque tellus etiam libero vitae. Netus quam ultricies sodales quisque lorem sapien. Bibendum molestie curabitur quam lacinia ridiculus; platea praesent. <br /> Maximus sodales nascetur scelerisque fermentum mi faucibus hendrerit pulvinar. Viverra fames magna sagittis id lacus montes volutpat et. Ad commodo libero venenatis inceptos, erat tempor finibus interdum erat. Orci eu arcu parturient quam velit mollis malesuada accumsan. Vulputate tortor praesent efficitur rhoncus natoque hac nisi sapien convallis. Eleifend lacus sollicitudin potenti sodales lobortis montes, accumsan ante felis. Sodales aenean porttitor nisi maecenas turpis nostra bibendum nisi. Arcu pharetra nullam id orci sodales est tortor sollicitudin pulvinar. <br /> Interdum dui id efficitur vivamus bibendum vulputate. Nibh sem duis; tortor amet nascetur est sociosqu in. Aenean non dolor tempor; commodo augue vitae. Amet montes habitant ad nostra arcu justo cursus. Dolor class gravida nulla vel felis felis. Cursus tempus scelerisque ullamcorper, auctor ornare elit. Molestie aliquam volutpat justo ultricies ad commodo adipiscing non. Finibus cubilia adipiscing nulla natoque facilisi quis eu platea. <br /> Maximus nascetur montes facilisis; congue convallis dapibus mus. Odio diam rutrum commodo nullam fames nascetur. Dis vivamus massa dictum taciti libero pellentesque. Mauris primis mus consequat sagittis sed ultrices proin molestie. Suscipit condimentum leo; molestie netus magna libero. Taciti curae tristique laoreet imperdiet platea tempus. Nostra augue magna praesent semper lacus dictum. Cubilia finibus nec vivamus mus odio ultricies aliquam. Tempor eget nullam eros; eu nisl montes? Mollis cubilia torquent eros nullam fringilla egestas id. <br /> Morbi phasellus mattis mattis dui accumsan. Libero inceptos donec ullamcorper ex non ultricies? Lobortis nec facilisis sed rutrum pulvinar gravida eros. Congue efficitur aptent vivamus phasellus eros viverra conubia elit primis. Neque suspendisse dignissim tempor per neque volutpat phasellus et tellus. Enim dui faucibus molestie cursus eros, sem aliquet proin. Maecenas torquent ornare nascetur fringilla; scelerisque cubilia justo montes. Nec odio fusce praesent tortor aliquam fusce interdum malesuada leo. Ultricies fringilla aptent urna diam amet. Egestas placerat sem inceptos varius, hac dignissim eros. </V2ModalDialog> </React.Fragment> ); }; ``` ## Close on click outside Use the `closeOnClickOutside` prop to control whether a user can dismiss the modal dialog by clicking on the overlay. The default value is `true`. ```jsx live () => { const modal = useOverlay('close-on-click-outside'); return ( <React.Fragment> <V2Button onClick={() => modal.open()} aria-haspopup="dialog"> Open Modal Dialog </V2Button> <V2ModalDialog header="Close on click outside" model="close-on-click-outside" closeOnClickOutside={false} > This Modal Dialog cannot be dismissed by clicking outside the dialog. </V2ModalDialog> </React.Fragment> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2ModalDialog" propTypeName="V2ModalDialogProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2ClassesTable title="V2ModalDialog" classes={[ModalBaseClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> Adheres to the <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/">WAI-ARIA Dialog design pattern</ExitLink>. See a <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/dialog/">modal dialog example</ExitLink> on the WAI-ARIA website. ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Esc', description: 'Closes the dialog.', }, { name: 'Tab', description: 'Moves focus to the next interactive element within the dialog. Once the last interactive element in the dialog is reached, pressing Tab again moves focus to the first interactive element within the dialog.', }, { name: 'Shift + Tab', description: 'Moves focus to the previous interactive element within the dialog. Once the first interactive element in the dialog is reached, pressing Shift + Tab again moves focus to the last interactive element within the dialog.', }, ]} /> ``` <h3>Modal Accessible Example</h3> ```jsx live () => { const modal = useOverlay('customization'); const footer = ( <Layout.Group> <V2Button onClick={() => { modal.close(); }} > I'm sold! </V2Button> <V2Button onClick={() => { modal.close(); }} > 'No thanks </V2Button> </Layout.Group> ); return ( <React.Fragment> <V2Button onClick={() => modal.open()} aria-haspopup="dialog"> Open Modal Dialog </V2Button> <V2ModalDialog header="Exciting modal examples you too can use" model="customization" footer={footer} > <p>Looking for an exciting new modal dialog?</p> <p>One that's also fully accessible?</p> <p>You've come to the right place</p> </V2ModalDialog> </React.Fragment> ); }; ``` <h3>Dialog Content</h3> The content included on the dialog must be accessible. ```jsx live () => { const modal = useOverlay('accessible-modal'); return ( <React.Fragment> <V2Button onClick={() => modal.open()} aria-haspopup="dialog"> Open Modal Dialog </V2Button> <V2ModalDialog header="Accessible modal" model="accessible-modal" css={{ 'abyss-modal-base-body': { gap: '$web.semantic.spacing.scale.lg', }, }} > The button below is accessible. <V2Button onClick={() => { console.log('Clicked!'); }} > Click me! </V2Button> </V2ModalDialog> </React.Fragment> ); }; ``` <h3>Triggering Elements</h3> Use the `aria-haspopup` attribute on buttons or other triggering elements that open content like dialogs, listboxes, trees, menus, grids, etc. Use a corresponding value that indicates what kind of popup will be displayed when the trigger element is activated. In turn, the element that pops up must be of the role indicated. In the case of V2ModalDialog, use `aria-haspop="dialog"` on the element that opens the modal dialog. V2ModalDialog sets `role="dialog"` on the dialog container internally. See the docs on <ExitLink href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup">aria-haspop</ExitLink> for more details. </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={V2ModalDialog} keys={['modalDialogV2']} /> ``` </Tab> --- id: nav-menu-v2 category: Navigation title: V2NavMenu description: Used to display a navigation menu with links and dropdowns. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=24-12784 subDirectory: NavMenu/v2 sourceIsTS: true --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="NavMenuPrimitives"></Docs.V2MigrationBanner> ``` ```jsx import { V2NavMenu } from '@uhg-abyss/web/ui/NavMenu'; ``` ## Overview The `V2NavMenu` component is a navigation menu that can contain links and dropdowns. It is designed to be accessible and customizable, allowing for a variety of use cases. Please follow the examples below for proper implementation of all the available V2NavMenu subcomponents. ## V2NavMenu.Root The `V2NavMenu.Root` is the provider component that contains all `V2NavMenu` subcomponents and accepts the following props: - `hasOverlay` is used to show or hide the overlay when a [dropdown menu](#dropdown-menu) is opened. The default value is `false`. - `zIndex` provides the ability to set the z-index value of the navigation menu. If `hasOverlay` is utilized, it will also adjust the z-index of the overlay and can assist with managing placement when multiple navigation menus are used on a single page. The default value is `101`. - `enableOutsideScroll` is used to allow the user to scroll, even when a navigation dropdown item is open. The default value is `false`. - `sticky` provides the ability to position the navigation menu at the top of the viewport. ```jsx live () => { const DropdownMenuContent = () => { return ( <V2NavMenu.Columns> Your V2NavMenu.Column components go here </V2NavMenu.Columns> ); }; return ( <V2NavMenu.Root zIndex={103} hasOverlay enableOutsideScroll={false} sticky> <V2NavMenu.List> <V2NavMenu.Item> <V2NavMenu.Trigger>Dropdown Menu</V2NavMenu.Trigger> <V2NavMenu.Content> <DropdownMenuContent /> </V2NavMenu.Content> </V2NavMenu.Item> </V2NavMenu.List> </V2NavMenu.Root> ); }; ``` ### Position viewport to trigger Add the optional `positionViewportToTrigger` prop to `V2NavMenu.Root` in order to position the [dropdown menu](#dropdown-menu) viewport with the corresponding trigger element. `positionViewportToTrigger`, also takes in an optional `minWidth` property to set the mininimum width of the viewport. The default min-width is `350px`. If not utilized, the default behavior will occur, and the dropdown menu will span a majority of the width of the navigation menu bar. ```jsx live () => { const DropdownMenuContent = ( <V2NavMenu.Columns> <V2NavMenu.Column title="Section Title"> <V2NavMenu.MenuItem title="HELLO" href="https://abyss.uhc.com/"> CSS-in-JS with best-in-class developer experience. </V2NavMenu.MenuItem> <V2NavMenu.Divider /> <V2NavMenu.MenuItem title="GOODBYE" href="https://abyss.uhc.com/" description="Description goes here" /> </V2NavMenu.Column> </V2NavMenu.Columns> ); return ( <V2NavMenu.Root positionViewportToTrigger={{ minWidth: 300 }}> <V2NavMenu.List> <V2NavMenu.Item> <V2NavMenu.Content>{DropdownMenuContent}</V2NavMenu.Content> <V2NavMenu.Trigger>Dropdown Menu 1</V2NavMenu.Trigger> </V2NavMenu.Item> <V2NavMenu.Item> <V2NavMenu.Trigger>Dropdown Menu 2</V2NavMenu.Trigger> <V2NavMenu.Content>{DropdownMenuContent}</V2NavMenu.Content> </V2NavMenu.Item> <V2NavMenu.Item> <V2NavMenu.Trigger>Dropdown Menu 3</V2NavMenu.Trigger> <V2NavMenu.Content>{DropdownMenuContent}</V2NavMenu.Content> </V2NavMenu.Item> </V2NavMenu.List> </V2NavMenu.Root> ); }; ``` ## V2NavMenu.List The `V2NavMenu.List` component is a wrapper for the top level menu items and should contain [V2NavMenu.Link](#v2navmenulink) or [V2NavMenu.Item](#v2navmenuitem) as direct children. ```jsx live () => { const DropdownMenuContent = () => { return ( <V2NavMenu.Columns> <V2NavMenu.Column title="Section Title"> <V2NavMenu.MenuItem title="HELLO" href="https://abyss.uhc.com/"> CSS-in-JS with best-in-class developer experience. </V2NavMenu.MenuItem> <V2NavMenu.MenuItem title="GOODBYE" href="https://abyss.uhc.com/" description="Description goes here" /> </V2NavMenu.Column> <V2NavMenu.Column> <V2NavMenu.MenuItem title="Sample onClick" onClick={() => console.log('onClick pressed')} description="A message will be logged to the console when this is clicked." /> </V2NavMenu.Column> <V2NavMenu.Column title="Other Section Title"> <V2NavMenu.MenuItem title="Colors" href="#" description="Description goes here" /> <V2NavMenu.MenuItem title="Colors" href="#" description="Description goes here" /> <V2NavMenu.Divider /> <V2NavMenu.MenuItem title="Colors" href="#" description="Description goes here" /> </V2NavMenu.Column> </V2NavMenu.Columns> ); }; return ( <V2NavMenu.Root zIndex={103} hasOverlay enableOutsideScroll={false}> <V2NavMenu.List> <V2NavMenu.Link title="link title" href="#"> Sample Link </V2NavMenu.Link> <V2NavMenu.Link onClick={() => console.log('Sample onClick clicked')}> Sample onClick </V2NavMenu.Link> <V2NavMenu.Item> <V2NavMenu.Trigger>Dropdown Menu</V2NavMenu.Trigger> <V2NavMenu.Content> <DropdownMenuContent /> </V2NavMenu.Content> </V2NavMenu.Item> </V2NavMenu.List> </V2NavMenu.Root> ); }; ``` ## V2NavMenu.Link The `V2NavMenu.Link` component is used to create a link or button in the top-level navigation menu and is a direct child of [V2NavMenu.List](#v2navmenulist). To use as a link, provide a valid value to the `href` prop. To use as a button, utilize the `onClick` prop instead. ```jsx live () => { return ( <V2NavMenu.Root> <V2NavMenu.List> <V2NavMenu.Link href="#">Sample Link</V2NavMenu.Link> </V2NavMenu.List> </V2NavMenu.Root> ); }; ``` ### Selected Use the `selected` prop to signal that a given item refers to the current path the user is on. This can be used on a `V2NavMenu.Link` or a `V2NavMenu.Trigger`. ```jsx live () => { return ( <V2NavMenu.Root> <V2NavMenu.List> <V2NavMenu.Link href="#" selected> Sample Link </V2NavMenu.Link> <V2NavMenu.Link onClick={() => console.log('Sample onClick clicked')}> Sample onClick </V2NavMenu.Link> <V2NavMenu.Item> <V2NavMenu.Trigger>Dropdown Menu</V2NavMenu.Trigger> <V2NavMenu.Content>Selected trigger Example</V2NavMenu.Content> </V2NavMenu.Item> </V2NavMenu.List> </V2NavMenu.Root> ); }; ``` ```jsx live () => { return ( <V2NavMenu.Root> <V2NavMenu.List> <V2NavMenu.Link href="#">Sample Link</V2NavMenu.Link> <V2NavMenu.Link onClick={() => console.log('Sample onClick clicked')}> Sample onClick </V2NavMenu.Link> <V2NavMenu.Item> <V2NavMenu.Trigger selected>Dropdown Menu</V2NavMenu.Trigger> <V2NavMenu.Content>Selected trigger Example</V2NavMenu.Content> </V2NavMenu.Item> </V2NavMenu.List> </V2NavMenu.Root> ); }; ``` ## Dropdown menu Use the following components to add a dropdown menu to the top level navigation menu. ```jsx live () => { return ( <V2NavMenu.Root> <V2NavMenu.List> <V2NavMenu.Item> <V2NavMenu.Trigger>Dropdown Menu</V2NavMenu.Trigger> <V2NavMenu.Content>Dropdown Content</V2NavMenu.Content> </V2NavMenu.Item> </V2NavMenu.List> </V2NavMenu.Root> ); }; ``` ### V2NavMenu.Item The `V2NavMenu.Item` component is the parent component for creating a dropdown menu item. As direct children, it should contain a trigger with content combination through usage of [V2NavMenu.Trigger](#v2navmenutrigger) and [V2NavMenu.Content](#v2navmenucontent). It is a direct child of [V2NavMenu.List](#v2navmenulist). ### V2NavMenu.Divider The `V2NavMenu.Divider` is a simple divider line component that allows you to add a visual separator between different `V2NavMenu.Item` components. ### V2NavMenu.Trigger The `V2NavMenu.Trigger` component is a button element that toggles viewing of the dropdown menu content. ## Dropdown menu content Use the following components to construct the content for the dropdown menu. ### V2NavMenu.Content The `V2NavMenu.Content` component is used to wrap the dropdown menu content and should be a direct child of [V2NavMenu.Item](#v2navmenuitem). Please see the following subcomponents below for constructing your dropdown menu content. ### V2NavMenu.Columns This component should be the outermost component of what is passed into content. It is used to provide styling for the dropdown container and the columns that go inside it. ```jsx live () => { return ( <V2NavMenu.Root> <V2NavMenu.List> <V2NavMenu.Item> <V2NavMenu.Trigger>Columns Example</V2NavMenu.Trigger> <V2NavMenu.Content> <V2NavMenu.Columns> Your V2NavMenu.Column components go here </V2NavMenu.Columns> </V2NavMenu.Content> </V2NavMenu.Item> </V2NavMenu.List> </V2NavMenu.Root> ); }; ``` ### V2NavMenu.Column This component should be a child of [V2NavMenu.Columns](#v2navmenucolumns). Each column that is a child of V2NavMenu.Columns will be a distinct column in the dropdown menu. The children of this component will be displayed vertically; you can use [V2NavMenu.MenuItem](#v2navmenumenuitem) as children to auto-format and style your input, or pass in your own custom renders to be displayed within the column. Available V2NavMenu.Column props: - `title`: Displays a bolded header as an `<h2>` at top of the column. - `href`: Converts a column header into a link. - `onClick`: Converts a column header into a button. It takes in a function that will be called when clicked. ```jsx live () => { return ( <V2NavMenu.Root zIndex={102}> <V2NavMenu.List> <V2NavMenu.Item> <V2NavMenu.Trigger>Column Examples</V2NavMenu.Trigger> <V2NavMenu.Content> <V2NavMenu.Columns> <V2NavMenu.Column title="Column Header"> Put V2NavMenu.MenuItem components or custom rendering here </V2NavMenu.Column> <V2NavMenu.Column title="Column Header Link" href="/web/developers/overview" > Put V2NavMenu.MenuItem components or custom rendering here </V2NavMenu.Column> <V2NavMenu.Column title="Column Header Button" onClick={() => { console.log('clicked'); }} > Put V2NavMenu.MenuItem components or custom rendering here </V2NavMenu.Column> </V2NavMenu.Columns> </V2NavMenu.Content> </V2NavMenu.Item> </V2NavMenu.List> </V2NavMenu.Root> ); }; ``` ```jsx live () => { return ( <V2NavMenu.Root> <V2NavMenu.List> <V2NavMenu.Item> <V2NavMenu.Trigger>Custom Column Example</V2NavMenu.Trigger> <V2NavMenu.Content> <V2NavMenu.Columns> <V2NavMenu.Column onClick={() => { console.log('clicked'); }} > <V2Card css={{ 'abyss-card-root': { width: 'max-content', padding: '0px', }, }} > <div> <Box padding="0px" css={{ 'abyss-box-root': { backgroundRepeat: 'no-repeat', backgroundSize: 'cover', borderTopLeftRadius: '7px', borderTopRightRadius: '7px', }, }} /> </div> <div style={{ padding: '16px' }}> <Layout.Group space={20}> <V2Avatar>JD</V2Avatar> <Layout.Stack alignItems="left"> <Text size="md" fontWeight="$semibold"> John Doe </Text> <Text size="sm" fontWeight="$normal" color="$gray7"> john.doe@uhg-abyss.com </Text> </Layout.Stack> </Layout.Group> </div> <Divider orientation="horizontal" color="$gray3" margin="0" /> <Layout.Group css={{ 'abyss-layout-group': { padding: '8px', }, }} > <V2Badge>admin</V2Badge> </Layout.Group> </V2Card> </V2NavMenu.Column> <V2NavMenu.Column title="Column 2"> <V2NavMenu.MenuItem title="HELLO" href="https://abyss.uhc.com/"> CSS-in-JS with best-in-class developer experience. </V2NavMenu.MenuItem> <V2NavMenu.Divider /> <V2NavMenu.MenuItem title="GOODBYE" href="https://abyss.uhc.com/" description="Description goes here" /> </V2NavMenu.Column> <V2NavMenu.Column title="Column 3"> <V2NavMenu.MenuItem title="HELLO" href="https://abyss.uhc.com/"> CSS-in-JS with best-in-class developer experience. </V2NavMenu.MenuItem> <V2NavMenu.Divider /> <V2NavMenu.MenuItem title="GOODBYE" href="https://abyss.uhc.com/" description="Description goes here" /> </V2NavMenu.Column> </V2NavMenu.Columns> </V2NavMenu.Content> </V2NavMenu.Item> </V2NavMenu.List> </V2NavMenu.Root> ); }; ``` ### V2NavMenu.MenuItem This component should be a child of [V2NavMenu.Column](#v2navmenucolumn). Use this component to automatically style links/buttons in your dropdown that only have a title, description, and link/button action. Available V2NavMenu.MenuItem props: - `title`: The title of the item. - `description`: The description of the item. - `href`: Converts the item into a link (on external links, an icon will appear next to the title to signify that it will open in a new window). - `onClick`: Converts the item into a button. It takes in a function that will be called when clicked. NOTE: each V2NavMenu.MenuItem should have an `href` or `onClick`, but not both. ```jsx live () => { return ( <V2NavMenu.Root zIndex={103}> <V2NavMenu.List> <V2NavMenu.Item> <V2NavMenu.Trigger>Menu Item Examples</V2NavMenu.Trigger> <V2NavMenu.Content> <V2NavMenu.Columns> <V2NavMenu.Column title="Column Title"> <V2NavMenu.MenuItem title="Item as link" href="#" description="Clicking here will redirect you to the link location." /> <V2NavMenu.Divider /> <V2NavMenu.MenuItem title="Item as button" onClick={() => console.log('onClick pressed')} description="A message will be logged to the console when this is clicked." /> </V2NavMenu.Column> <V2NavMenu.Column> <V2NavMenu.MenuItem title="Item as link" href="#" description="Clicking here will redirect you to the link location." /> </V2NavMenu.Column> <V2NavMenu.Column> Put more V2NavMenu.MenuItem components or custom rendering here </V2NavMenu.Column> </V2NavMenu.Columns> </V2NavMenu.Content> </V2NavMenu.Item> </V2NavMenu.List> </V2NavMenu.Root> ); }; ``` ### V2NavMenu.MenuItemUnstyled The `V2NavMenu.MenuItemUnstyled` component is an unstyled wrapper that ensures proper menu closing behavior when using custom interactive elements. Use this component when you need to include your own custom-styled buttons or links in the navigation menu while maintaining the automatic menu closure on click that the standard MenuItem provides. ```jsx live () => { return ( <V2NavMenu.Root zIndex={103}> <V2NavMenu.List> <V2NavMenu.Item> <V2NavMenu.Trigger>Menu Item Examples</V2NavMenu.Trigger> <V2NavMenu.Content> <V2NavMenu.Columns> <V2NavMenu.Column title="With Unstyled Wrapper"> <V2NavMenu.MenuItemUnstyled> <li> <Text>Menu closes on click</Text> <Layout.Space space={8} /> <V2Button size="sm" onClick={() => console.log('onClick pressed')} > Menu Action </V2Button> </li> </V2NavMenu.MenuItemUnstyled> </V2NavMenu.Column> <V2NavMenu.Column title="Without Unstyled Wrapper"> <li> <Text>Menu stays open on click</Text> <Layout.Space space={8} /> <V2Button size="sm" onClick={() => console.log('onClick pressed')} > Menu Action </V2Button> </li> </V2NavMenu.Column> </V2NavMenu.Columns> </V2NavMenu.Content> </V2NavMenu.Item> </V2NavMenu.List> </V2NavMenu.Root> ); }; ``` ### StateRouter The `StateRouter` component is used to manage the routing within the dropdown menu. It allows for nested routes and provides a way to navigate between different sets of dropdown menu content. ```jsx live () => { const DropdownMenuContent = () => { return ( <V2NavMenu.Columns> <V2NavMenu.Column title="Section Title"> <Layout.Stack grow> <V2NavMenu.MenuItem title="HELLO" href="https://abyss.uhc.com/"> CSS-in-JS with best-in-class developer experience. </V2NavMenu.MenuItem> <V2NavMenu.MenuItem title="GOODBYE" href="https://abyss.uhc.com/" description="Description goes here" /> <V2NavMenu.Divider /> <V2NavMenu.MenuItem title="Sample onClick" onClick={() => console.log('onClick pressed')} description="A message will be logged to the console when this is clicked." /> </Layout.Stack> </V2NavMenu.Column> <V2NavMenu.Column> <V2Header.DrawerLink title="Utility Plans" path="/dropdown/utilityPlans" /> </V2NavMenu.Column> <V2NavMenu.Column title="Other Section Title"> <V2NavMenu.MenuItem title="Colors" href="#" description="Description goes here" /> <V2NavMenu.MenuItem title="Colors" href="#" description="Description goes here" /> <V2NavMenu.MenuItem title="Colors" href="#" description="Description goes here" /> </V2NavMenu.Column> </V2NavMenu.Columns> ); }; const UtilityPlanTypes = () => { return ( <V2NavMenu.Columns css={{ paddingTop: 0 }}> <V2NavMenu.Column title=" Utility Plans"> <Layout.Stack alignItems="left"> <V2Link fontWeight="$bold" href="#"> Gas </V2Link> <V2Link fontWeight="$bold" href="#"> Electric </V2Link> <V2Link fontWeight="$bold" href="#"> Water </V2Link> </Layout.Stack> </V2NavMenu.Column> </V2NavMenu.Columns> ); }; return ( <V2NavMenu.Root zIndex={102}> <V2NavMenu.List> <V2NavMenu.Item> <V2NavMenu.Trigger>Dropdown Menu</V2NavMenu.Trigger> <V2NavMenu.Content> <StateRouter.Provider initialPath="/dropdown"> <V2NavMenu.RouterHeader /> <StateRouter.Routes> <StateRouter.Route path="/dropdown" title="Dropdown Menu"> <DropdownMenuContent /> </StateRouter.Route> <StateRouter.Route path="/dropdown/utilityPlans" title="Utility Plans" > <UtilityPlanTypes /> </StateRouter.Route> </StateRouter.Routes> </StateRouter.Provider> </V2NavMenu.Content> </V2NavMenu.Item> </V2NavMenu.List> </V2NavMenu.Root> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2NavMenu.Root" propTypeName="V2NavigationMenuRootProps" /> ``` ```jsx render <Docs.V2WebPropsTable title="V2NavMenu.List" propTypeName="V2NavigationMenuListProps" /> ``` ```jsx render <Docs.V2WebPropsTable title="V2NavMenu.Item" propTypeName="V2NavigationMenuItemProps" /> ``` ```jsx render <Docs.V2WebPropsTable title="V2NavMenu.Link" propTypeName="V2NavigationMenuLinkProps" /> ``` ```jsx render <Docs.V2WebPropsTable title="V2NavMenu.Trigger" propTypeName="V2NavigationMenuTriggerProps" /> ``` ```jsx render <Docs.V2WebPropsTable title="V2NavMenu.Column" propTypeName="V2NavigationMenuColumnProps" /> ``` ```jsx render <Docs.V2WebPropsTable title="V2NavMenu.Columns" propTypeName="V2NavigationMenuColumnsProps" /> ``` ```jsx render <Docs.V2WebPropsTable title="V2NavMenu.MenuItem" propTypeName="V2NavigationMenuMenuItemProps" /> ``` ```jsx render <Docs.V2WebPropsTable title="V2NavMenu.Content" propTypeName="V2NavigationMenuContentProps" /> ``` ```jsx render <Docs.V2ClassesTable title="V2NavMenu.Root" classes={[NavigationMenuRootClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2NavMenu.List" classes={[NavigationMenuListClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2NavMenu.Item" classes={[NavigationMenuItemClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2NavMenu.Link" classes={[NavigationMenuLinkClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2NavMenu.Trigger" classes={[NavigationMenuTriggerClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2NavMenu.Column" classes={[NavigationMenuColumnClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2NavMenu.Columns" classes={[NavigationMenuColumnsClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2NavMenu.MenuItem" classes={[NavigationMenuMenuItemClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2NavMenu.Content" classes={[NavigationMenuContentClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2NavMenu.Divider" classes={[NavigationMenuDividerClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> <h3> Reduced Motion </h3> Animations and transitions that have been changed when a user has `prefers-reduced-motion` set to `reduced`: - Transition upon expand/collapse is removed <h3> Implementation </h3> The example below showcases a complex menu that includes all the right accessibility settings ```jsx live () => { const DropdownMenuContent2 = () => ( <V2NavMenu.Columns> <V2NavMenu.Column title="Medicare plan types"> <V2NavMenu.MenuItem title="Medicare advantage plans" href="https://www.uhc.com/medicare/shop/medicare-advantage-plans.html" /> <V2NavMenu.MenuItem title="Medicare Supplement plans" href="https://www.uhc.com/medicare/shop/medicare-supplement-plans.html" /> <V2NavMenu.MenuItem title="Medicare prescription drug plans" href="https://www.uhc.com/medicare/shop/prescription-drug-plans.html" /> <V2NavMenu.MenuItem title="Dual-Special Needs plan (D-SNP)" href="https://www.uhc.com/medicare/shop/dual-special-needs-plans.html" /> <li> <V2Link after={<IconSymbol icon="chevron_right" size={20} />} href="https://www.uhc.com/medicare/shop.html?WT.mc_id=8031053" > Shop all Medicare plans </V2Link> </li> </V2NavMenu.Column> <V2NavMenu.Column title="Get help with choosing a plan"> <V2NavMenu.MenuItem title="Help me find a plan" href="https://www.uhc.com/medicare/plan-recommendation-engine.html" /> <V2NavMenu.MenuItem title="Estimate drug costs" href="https://www.uhc.com/medicare/health-plans/estimate-drug-costs.html" /> <V2NavMenu.MenuItem title="Search for a pharmacy" href="https://www.uhc.com/medicare/health-plans/aarp-pharmacy.html" /> <V2NavMenu.MenuItem title="Find a doctor" href="https://connect.werally.com/county-plan-selection/uhc.mnr/zip" /> <V2NavMenu.MenuItem title="Find a dentist" href="https://connect.werally.com/plan-location" /> <V2NavMenu.MenuItem title="Medicare overview" href="https://www.uhc.com/medicare/medicare-education.html" /> </V2NavMenu.Column> <V2NavMenu.Column> <li> <Layout.Stack alignItems="left"> <h6 aria-level="2">Find Medicare plans near you</h6> <V2TextInput label="Enter ZIP code" isClearable /> <V2Button type="submit" style={{ marginTop: 15 }}> Find plans </V2Button> <Divider /> <h6 aria-level="2">Not sure where to start?</h6> <p> Answer a few questions and get plan recommendations based on the information you provide. <br /> <V2Link after={<IconSymbol icon="chevron_right" size={20} />} href="https://www.uhc.com/medicare/plan-recommendation-engine.html" > Get started </V2Link> </p> </Layout.Stack> </li> </V2NavMenu.Column> </V2NavMenu.Columns> ); const DropdownMenuContent = () => ( <V2NavMenu.Columns> <V2NavMenu.Column title="Plan types"> <V2NavMenu.MenuItem title="Short term plans" href="https://www.uhc.com/individuals-families/short-term-health-insurance" /> <V2NavMenu.MenuItem title="ACA marketplace plans" href="https://www.uhc.com/individuals-families/aca-marketplace" /> <V2NavMenu.MenuItem title="Plans through work" href="https://www.uhc.com/individuals-families/health-plans-through-work" /> <V2NavMenu.MenuItem title="All health insurance plans" href="https://www.uhc.com/individuals-families" /> </V2NavMenu.Column> <V2NavMenu.Column title="Understanding health insurance"> <V2NavMenu.MenuItem title="Short term vs. ACA plans" href="https://www.uhc.com/understanding-health-insurance/types-of-health-insurance/aca-vs-short-term" /> <V2NavMenu.MenuItem title="Open enrollment" href="https://www.uhc.com/understanding-health-insurance/open-enrollment" /> <V2NavMenu.MenuItem title="Qualifying life events" href="https://www.uhc.com/understanding-health-insurance/open-enrollment/qualifying-life-events" /> <V2NavMenu.MenuItem title="Medicaid renewal" href="https://www.uhc.com/understanding-health-insurance/medicaid-renewal-redetermination-coverage-options" /> </V2NavMenu.Column> <V2NavMenu.Column title="Need help finding a plan?"> <V2NavMenu.MenuItem title="Find your plan" description="Answer a few questions to see which insurance options may be available for you." href="https://www.uhc.com/insurance-plan-finder" /> </V2NavMenu.Column> </V2NavMenu.Columns> ); const DropdownMenuContent3 = () => ( <V2NavMenu.Columns> <V2NavMenu.Column title=""> <V2NavMenu.MenuItem title="Small business" href="https://www.uhc.com/employer/small-business" description="Learn more about our group health insurance plans for small business and get a quote." /> </V2NavMenu.Column> <V2NavMenu.Column title=""> <V2NavMenu.MenuItem title="Large organizations" href="https://www.uhc.com/employer/small-business" description="Learn more about our products for National Accounts, public sector and group retiree solutions." /> </V2NavMenu.Column> <V2NavMenu.Column title=""> <V2NavMenu.MenuItem title="All group plans for employers" href="https://www.uhc.com/employer/small-business" description="Explore all of our group health insurance plans and benefits." /> </V2NavMenu.Column> </V2NavMenu.Columns> ); return ( <V2NavMenu.Root zIndex={103} hasOverlay enableOutsideScroll={false}> <V2NavMenu.List> <V2NavMenu.Item> <V2NavMenu.Trigger>Medicare</V2NavMenu.Trigger> <V2NavMenu.Content> <DropdownMenuContent2 /> </V2NavMenu.Content> </V2NavMenu.Item> <V2NavMenu.Item> <V2NavMenu.Content> <DropdownMenuContent /> </V2NavMenu.Content> <V2NavMenu.Trigger>Health Insurance Plans</V2NavMenu.Trigger> </V2NavMenu.Item> <V2NavMenu.Item> <V2NavMenu.Trigger>Group plans for employers</V2NavMenu.Trigger> <V2NavMenu.Content> <DropdownMenuContent3 /> </V2NavMenu.Content> </V2NavMenu.Item> <V2NavMenu.Link href="https://www.uhc.com/shop-online-health-insurance-plans"> Shop all plans </V2NavMenu.Link> </V2NavMenu.List> </V2NavMenu.Root> ); }; ``` ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Tab', description: 'Moves focus to the next focusable element.', }, { name: 'Enter', description: 'Redirects to the link if the menu bar item is a redirect, or opens the relevant dropdown menu if the item has one.', }, { name: 'Space', description: 'If focus on a menu bar item with a dropdown, opens the relevant dropdown menu.', }, { name: 'Left Arrow', description: 'Focuses the previous menu bar item.', }, { name: 'Up Arrow', description: 'Focuses the previous menu bar item.', }, { name: 'Right Arrow', description: 'Focuses the next menu bar item.', }, { name: 'Down Arrow', description: 'Focuses the next menu bar item. If focus is on an open menu bar item, moves focus into its dropdown menu instead.', }, { name: 'Escape', description: 'Closes open dropdown menu and moves focus to its menu bar item.', }, { name: 'Home', description: 'Moves focus to the first item in the menu.', }, { name: 'End', description: 'Moves focus to the last item in the menu.', }, ]} /> ``` </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={'V2NavMenu'} keys={['navMenuV2']} /> ``` </Tab> --- id: nav-menu category: Navigation title: NavMenu description: Used to display a navigation menu with links and dropdowns. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=0-1557 subDirectory: NavMenu/v1 --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="NavMenuPrimitives"></Docs.V2MigrationBanner> ``` ```jsx import { NavMenuPrimitives } from '@uhg-abyss/web/ui/NavMenu'; ``` ## NavMenuPrimitives.Root `zIndex` is prop for `NavMenuPrimitives.Root` which gives ability to pass index value to make Navmenu standout top in case of overlay or multiple Navmenu's in one page. The default value is 101. `hasOverlay` prop of `NavMenuPrimitives.Root` is used to show or hide overlay when dropdown menu is opened in navmenu. The default value is `false`. `enableOutsideScroll` is a prop of `NavMenuPrimitives.Root`. It is used to allow the user to scroll, even when a `NavMenu` dropdown item is open. The default value is `false`. ```jsx live () => { const DropdownMenuContent = () => { return ( <NavMenuPrimitives.Columns> Your NavMenuPrimitives.Column components go here </NavMenuPrimitives.Columns> ); }; return ( <NavMenuPrimitives.Root zIndex={103} hasOverlay enableOutsideScroll={false}> <NavMenuPrimitives.List> <NavMenuPrimitives.Item> <NavMenuPrimitives.Trigger>Dropdown Menu</NavMenuPrimitives.Trigger> <NavMenuPrimitives.Content> <DropdownMenuContent /> </NavMenuPrimitives.Content> </NavMenuPrimitives.Item> </NavMenuPrimitives.List> <NavMenuPrimitives.Viewport /> </NavMenuPrimitives.Root> ); }; ``` ## NavMenuPrimitives.List ```jsx live () => { const DropdownMenuContent = () => { return ( <NavMenuPrimitives.Columns> <NavMenuPrimitives.Column title="Section Title"> <NavMenuPrimitives.MenuItem title="HELLO" href="https://abyss.uhc.com/" > CSS-in-JS with best-in-class developer experience. </NavMenuPrimitives.MenuItem> <NavMenuPrimitives.MenuItem title="GOODBYE" href="https://abyss.uhc.com/" description="Description goes here" /> </NavMenuPrimitives.Column> <NavMenuPrimitives.Column> <NavMenuPrimitives.MenuItem title="Sample onClick" onClick={() => console.log('onClick pressed')} description="A message will be logged to the console when this is clicked." /> </NavMenuPrimitives.Column> <NavMenuPrimitives.Column title="Other Section Title"> <NavMenuPrimitives.MenuItem title="Colors" href="#" description="Description goes here" /> <NavMenuPrimitives.MenuItem title="Colors" href="#" description="Description goes here" /> <NavMenuPrimitives.MenuItem title="Colors" href="#" description="Description goes here" /> </NavMenuPrimitives.Column> </NavMenuPrimitives.Columns> ); }; return ( <NavMenuPrimitives.Root zIndex={103} hasOverlay enableOutsideScroll={false}> <NavMenuPrimitives.List> <NavMenuPrimitives.Link href="#">Sample Link</NavMenuPrimitives.Link> <NavMenuPrimitives.Link onClick={() => console.log('Sample onClick clicked')} > Sample onClick </NavMenuPrimitives.Link> <NavMenuPrimitives.Item> <NavMenuPrimitives.Trigger>Dropdown Menu</NavMenuPrimitives.Trigger> <NavMenuPrimitives.Content> <DropdownMenuContent /> </NavMenuPrimitives.Content> </NavMenuPrimitives.Item> </NavMenuPrimitives.List> <NavMenuPrimitives.Viewport /> </NavMenuPrimitives.Root> ); }; ``` ## NavMenuPrimitives.Columns This component should be the outermost component of what is passed into content. It is used to provide styling for the dropdown container and the columns that go inside it. ```jsx live () => { return ( <NavMenuPrimitives.Root> <NavMenuPrimitives.List> <NavMenuPrimitives.Item> <NavMenuPrimitives.Trigger>Columns Example</NavMenuPrimitives.Trigger> <NavMenuPrimitives.Content> <NavMenuPrimitives.Columns> Your NavMenuPrimitives.Column components go here{' '} </NavMenuPrimitives.Columns> </NavMenuPrimitives.Content> </NavMenuPrimitives.Item> </NavMenuPrimitives.List> <NavMenuPrimitives.Viewport /> </NavMenuPrimitives.Root> ); }; ``` ## NavMenuPrimitives.Column This component should be a child of NavMenuPrimitives.Columns. Each column that is a child of NavMenuPrimitives.Columns will be a distinct column in the dropdown menu. Pass in a value for the title prop if you would like a bolded title to appear at the top of the column. NavMenuPrimitives.Column can also accept a href prop for where the link will redirect to when clicked, or an onClick prop for a function that will be called when clicked. The children of this component will be displayed vertically; you can use NavMenuPrimitives.MenuItem as children to auto-format and style your input, or pass in your own custom renders to be displayed within the column. ```jsx live () => { return ( <NavMenuPrimitives.Root> <NavMenuPrimitives.List> <NavMenuPrimitives.Item> <NavMenuPrimitives.Trigger>Column Examples</NavMenuPrimitives.Trigger> <NavMenuPrimitives.Content> <NavMenuPrimitives.Columns> <NavMenuPrimitives.Column title="Column Header"> Put NavMenuPrimitives.MenuItem components or custom rendering here </NavMenuPrimitives.Column> <NavMenuPrimitives.Column title="Column Header Link" href="/web/developers/overview" > Put NavMenuPrimitives.MenuItem components or custom rendering here </NavMenuPrimitives.Column> <NavMenuPrimitives.Column title="Column Header Button" onClick={() => { console.log('clicked'); }} > Put NavMenuPrimitives.MenuItem components or custom rendering here </NavMenuPrimitives.Column> </NavMenuPrimitives.Columns> </NavMenuPrimitives.Content> </NavMenuPrimitives.Item> </NavMenuPrimitives.List> <NavMenuPrimitives.Viewport /> </NavMenuPrimitives.Root> ); }; ``` ## NavMenuPrimitives.MenuItem This component should be a child of NavMenuPrimitives.Column. Use this component to automatically style links in your dropdown that only have a title, description, and redirect link. Use the title prop for the title of the item, the description prop for the description, the href prop for where the link will redirect to when clicked, and the onClick prop for a function that will be called when clicked. If the href points to an external link, an icon will appear next to the title to signify that it will open in a new window. NOTE: each NavMenuPrimitives.MenuItem should have one of href or onClick, but not both. ```jsx live () => { return ( <NavMenuPrimitives.Root> <NavMenuPrimitives.List> <NavMenuPrimitives.Item> <NavMenuPrimitives.Trigger>Item Example</NavMenuPrimitives.Trigger> <NavMenuPrimitives.Content> <NavMenuPrimitives.Columns> <NavMenuPrimitives.Column> <NavMenuPrimitives.MenuItem title="Sample NavMenuPrimitives.MenuItem" description="Your description goes here" onClick={() => console.log('onClick pressed')} /> Put more NavMenuPrimitives.MenuItem components or custom rendering here </NavMenuPrimitives.Column> </NavMenuPrimitives.Columns> </NavMenuPrimitives.Content> </NavMenuPrimitives.Item> </NavMenuPrimitives.List> <NavMenuPrimitives.Viewport /> </NavMenuPrimitives.Root> ); }; ``` ### MenuItemUnstyled The `NavMenuPrimitives.MenuItemUnstyled` component is an unstyled wrapper that ensures proper menu closing behavior when using custom interactive elements. Use this component when you need to include your own custom-styled buttons or links in the navigation menu while maintaining the automatic menu closure on click that the standard MenuItem provides. ```jsx live () => { return ( <NavMenuPrimitives.Root> <NavMenuPrimitives.List> <NavMenuPrimitives.Item> <NavMenuPrimitives.Trigger>Item Example</NavMenuPrimitives.Trigger> <NavMenuPrimitives.Content> <NavMenuPrimitives.Columns> <NavMenuPrimitives.Column title="With Unstyled Wrapper"> <NavMenuPrimitives.MenuItemUnstyled> <li> <Text>Menu closes on click</Text> <Layout.Space space={8} /> <V2Button size="sm" onClick={() => console.log('onClick pressed')} > Menu Action </V2Button> </li> </NavMenuPrimitives.MenuItemUnstyled> </NavMenuPrimitives.Column> <NavMenuPrimitives.Column title="Without Unstyled Wrapper"> <li> <Text>Menu stays open on click</Text> <Layout.Space space={8} /> <V2Button size="sm" onClick={() => console.log('onClick pressed')} > Menu Action </V2Button> </li> </NavMenuPrimitives.Column> </NavMenuPrimitives.Columns> </NavMenuPrimitives.Content> </NavMenuPrimitives.Item> </NavMenuPrimitives.List> <NavMenuPrimitives.Viewport /> </NavMenuPrimitives.Root> ); }; ``` ## Variant Use the variant prop to change the appearance of the NavMenu. Possible values are default and inverted, and the default value is default. ```jsx live () => { return ( <NavMenuPrimitives.Root> <NavMenuPrimitives.List> <NavMenuPrimitives.Link href="#">Sample Link</NavMenuPrimitives.Link> <NavMenuPrimitives.Link onClick={() => console.log('Sample onClick clicked')} > Sample onClick </NavMenuPrimitives.Link> <NavMenuPrimitives.Item> <NavMenuPrimitives.Trigger>Dropdown Menu</NavMenuPrimitives.Trigger> <NavMenuPrimitives.Content> Variant trigger Example </NavMenuPrimitives.Content> </NavMenuPrimitives.Item> </NavMenuPrimitives.List> <NavMenuPrimitives.Viewport /> </NavMenuPrimitives.Root> ); }; ``` ```jsx live () => { return ( <NavMenuPrimitives.Root variant="inverted"> <NavMenuPrimitives.List> <NavMenuPrimitives.Link href="#" variant="inverted"> Sample Link </NavMenuPrimitives.Link> <NavMenuPrimitives.Link onClick={() => console.log('Sample onClick clicked')} variant="inverted" > Sample onClick </NavMenuPrimitives.Link> <NavMenuPrimitives.Item> <NavMenuPrimitives.Trigger variant="inverted"> Dropdown Menu </NavMenuPrimitives.Trigger> <NavMenuPrimitives.Content> Variant trigger Example </NavMenuPrimitives.Content> </NavMenuPrimitives.Item> </NavMenuPrimitives.List> <NavMenuPrimitives.Viewport /> </NavMenuPrimitives.Root> ); }; ``` ## Disabled NavMenuPrimitives.MenuItem Set the isDisabled prop to true to disable an individual NavMenuPrimitives.MenuItem. ```jsx live () => { return ( <NavMenuPrimitives.Root> <NavMenuPrimitives.List> <NavMenuPrimitives.Item> <NavMenuPrimitives.Trigger> Dropdown Example </NavMenuPrimitives.Trigger> <NavMenuPrimitives.Content> <NavMenuPrimitives.Columns> <NavMenuPrimitives.Column title="Section Title"> <NavMenuPrimitives.MenuItem title="HELLO" href="#" description="CSS-in-JS with best-in-class developer experience." isDisabled /> <NavMenuPrimitives.MenuItem title="GOODBYE" href="#" description="Description goes here" /> </NavMenuPrimitives.Column> <NavMenuPrimitives.Column> <NavMenuPrimitives.MenuItem title="Sample onClick" onClick={() => console.log('onClick pressed')} description="A message will be logged to the console when this is clicked." isDisabled /> </NavMenuPrimitives.Column> </NavMenuPrimitives.Columns> </NavMenuPrimitives.Content> </NavMenuPrimitives.Item> </NavMenuPrimitives.List> <NavMenuPrimitives.Viewport /> </NavMenuPrimitives.Root> ); }; ``` ## NavMenuPrimitives.Provider In order to take advantage of the following features, you'll need to wrap your NavMenuPrimitives in a `NavMenuPrimitives.Provider`. ### Position viewport to trigger Add the `positionViewportToTrigger` prop to `NavMenuPrimitives.Provider` in order to position the dropdown menu viewport with the corresponding trigger element. `positionViewportToTrigger`, also takes in an optional `minWidth` property to set the min-width of the viewport. The default min-width is `350px`. ```jsx live () => { const DropdownMenuContent = ( <NavMenuPrimitives.Columns> <NavMenuPrimitives.Column title="Section Title"> <NavMenuPrimitives.MenuItem title="HELLO" href="https://abyss.uhc.com/"> CSS-in-JS with best-in-class developer experience. </NavMenuPrimitives.MenuItem> <NavMenuPrimitives.MenuItem title="GOODBYE" href="https://abyss.uhc.com/" description="Description goes here" /> </NavMenuPrimitives.Column> </NavMenuPrimitives.Columns> ); return ( <NavMenuPrimitives.Provider positionViewportToTrigger={{ minWidth: 300 }}> <NavMenuPrimitives.Root> <NavMenuPrimitives.List> <NavMenuPrimitives.Item> <NavMenuPrimitives.Content> {DropdownMenuContent} </NavMenuPrimitives.Content> <NavMenuPrimitives.Trigger> Dropdown Menu 1 </NavMenuPrimitives.Trigger> </NavMenuPrimitives.Item> <NavMenuPrimitives.Item> <NavMenuPrimitives.Trigger> Dropdown Menu 2 </NavMenuPrimitives.Trigger> <NavMenuPrimitives.Content> {DropdownMenuContent} </NavMenuPrimitives.Content> </NavMenuPrimitives.Item> <NavMenuPrimitives.Item> <NavMenuPrimitives.Trigger> Dropdown Menu 3 </NavMenuPrimitives.Trigger> <NavMenuPrimitives.Content> {DropdownMenuContent} </NavMenuPrimitives.Content> </NavMenuPrimitives.Item> </NavMenuPrimitives.List> <NavMenuPrimitives.Viewport /> </NavMenuPrimitives.Root> </NavMenuPrimitives.Provider> ); }; ``` ### SEO mode Use the `seoMode` prop to ensure all drop-down menu content is rendered at all times and available for SEO purposes. Note When using `seoMode` the `NavMenuPrimitives.Viewport` component should no longer be used. ```jsx live () => { const DropdownMenuContent = ( <NavMenuPrimitives.Columns> <NavMenuPrimitives.Column title="Section Title"> <NavMenuPrimitives.MenuItem title="HELLO" href="https://abyss.uhc.com/"> CSS-in-JS with best-in-class developer experience. </NavMenuPrimitives.MenuItem> <NavMenuPrimitives.MenuItem title="GOODBYE" href="https://abyss.uhc.com/" description="Description goes here" /> </NavMenuPrimitives.Column> </NavMenuPrimitives.Columns> ); return ( <NavMenuPrimitives.Provider seoMode> <NavMenuPrimitives.Root zIndex={102}> <NavMenuPrimitives.List> <NavMenuPrimitives.Item> <NavMenuPrimitives.Content> {DropdownMenuContent} </NavMenuPrimitives.Content> <NavMenuPrimitives.Trigger> Dropdown Menu 1 </NavMenuPrimitives.Trigger> </NavMenuPrimitives.Item> <NavMenuPrimitives.Item> <NavMenuPrimitives.Trigger> Dropdown Menu 2 </NavMenuPrimitives.Trigger> <NavMenuPrimitives.Content> {DropdownMenuContent} </NavMenuPrimitives.Content> </NavMenuPrimitives.Item> <NavMenuPrimitives.Item> <NavMenuPrimitives.Trigger> Dropdown Menu 3 </NavMenuPrimitives.Trigger> <NavMenuPrimitives.Content> {DropdownMenuContent} </NavMenuPrimitives.Content> </NavMenuPrimitives.Item> </NavMenuPrimitives.List> </NavMenuPrimitives.Root> </NavMenuPrimitives.Provider> ); }; ``` ## StateRouter ```jsx live () => { const DropdownMenuContent = () => { return ( <NavMenuPrimitives.Columns> <NavMenuPrimitives.Column title="Section Title"> <Layout.Stack grow> <NavMenuPrimitives.MenuItem title="HELLO" href="https://abyss.uhc.com/" > CSS-in-JS with best-in-class developer experience. </NavMenuPrimitives.MenuItem> <NavMenuPrimitives.MenuItem title="GOODBYE" href="https://abyss.uhc.com/" description="Description goes here" /> <NavMenuPrimitives.MenuItem title="Sample onClick" onClick={() => console.log('onClick pressed')} description="A message will be logged to the console when this is clicked." /> </Layout.Stack> </NavMenuPrimitives.Column> <NavMenuPrimitives.Column> <PageHeaderPrimitives.DrawerLink title="Utility Plans" path="/dropdown/utilityPlans" /> </NavMenuPrimitives.Column> <NavMenuPrimitives.Column title="Other Section Title"> <NavMenuPrimitives.MenuItem title="Colors" href="#" description="Description goes here" /> <NavMenuPrimitives.MenuItem title="Colors" href="#" description="Description goes here" /> <NavMenuPrimitives.MenuItem title="Colors" href="#" description="Description goes here" /> </NavMenuPrimitives.Column> </NavMenuPrimitives.Columns> ); }; const UtilityPlanTypes = () => { return ( <NavMenuPrimitives.Columns css={{ paddingTop: 0 }}> <NavMenuPrimitives.Column title=" Utility Plans"> <Layout.Stack alignItems="left"> <Link css={{ fontWeight: 'bold', fontSize: '16px' }} href="#" variant="custom" > Gas </Link> <Link css={{ fontWeight: 'bold', fontSize: '16px' }} href="#" variant="custom" > Electric </Link> <Link css={{ fontWeight: 'bold', fontSize: '16px' }} href="#" variant="custom" > Water </Link> </Layout.Stack> </NavMenuPrimitives.Column> </NavMenuPrimitives.Columns> ); }; return ( <NavMenuPrimitives.Root> <NavMenuPrimitives.List> <NavMenuPrimitives.Link href="/">Sample Link</NavMenuPrimitives.Link> <NavMenuPrimitives.Item> <NavMenuPrimitives.Trigger>Dropdown Menu</NavMenuPrimitives.Trigger> <NavMenuPrimitives.Content> <StateRouter.Provider initialPath="/dropdown"> <NavMenuPrimitives.RouterHeader /> <StateRouter.Routes> <StateRouter.Route path="/dropdown" title="Dropdown Menu"> <DropdownMenuContent /> </StateRouter.Route> <StateRouter.Route path="/dropdown/utilityPlans" title="Utility Plans" > <UtilityPlanTypes /> </StateRouter.Route> </StateRouter.Routes> </StateRouter.Provider> </NavMenuPrimitives.Content> </NavMenuPrimitives.Item> </NavMenuPrimitives.List> <NavMenuPrimitives.Viewport /> </NavMenuPrimitives.Root> ); }; ``` </Tab> <Tab label="NavMenu Dynamic"> ```jsx render <Layout.Stack alignItems="left"> <Alert title="Deprecated"> The dynamic version of the NavMenu component is deprecated and will be removed in version 2.0 of Abyss. This component is in maintenance status and will only receive bugfixes if found. Please migrate your component over to NavMenuPrimitives </Alert> <h2>Usage</h2> </Layout.Stack> ``` ```jsx live () => { const navMenuItems = [ { title: 'Sample Link', href: '#' }, { title: 'Sample onClick', onClick: () => console.log('Sample onClick clicked'), }, { title: 'Dropdown Menu', content: ( <NavMenu.Columns> <NavMenu.Column title="Section Title" href="/web/developers/overview"> <NavMenu.Item title="HELLO" href="#" description="CSS-in-JS with best-in-class developer experience." /> <NavMenu.Item title="GOODBYE" href="#" description="Description goes here" /> </NavMenu.Column> <NavMenu.Column> <NavMenu.Item title="Sample onClick" onClick={() => console.log('onClick pressed')} description="A message will be logged to the console when this is clicked." /> </NavMenu.Column> <NavMenu.Column title="Other Section Title"> <NavMenu.Item title="Colors" href="#" description="Description goes here" /> <NavMenu.Item title="Colors" href="#" description="Description goes here" /> <NavMenu.Item title="Colors" href="#" description="Description goes here" /> </NavMenu.Column> </NavMenu.Columns> ), }, ]; return <NavMenu items={navMenuItems} />; }; ``` ```jsx render <h2>Items</h2> ``` Use the `items` prop to specify what will be displayed in the NavMenu. The prop requires an array of objects that have the form: ```js { title: node, href: string, onClick: function, content: node, } ``` <br /> Each object should have one of `href`, `onClick`, and `content` - if the object has a value for `href` or `onClick`, then in the menu it will be a link to that page, or a button, respectively; if, instead, it has `content` present, in the menu it will be a dropdown menu that, when opened, will display the objects inside `content`. For `content`, you can pass in your own [custom elements to render](#custom-rendering), but we strongly recommend that you use our [NavMenu.Columns](#navmenucolumns), [NavMenu.Column](#navmenucolumn), and [NavMenu.Item](#navmenuitem) components for two reasons: - The styling and formatting are already taken care of by the components. - When the screen size is small enough (ex. on phones), the columns in the dropdown menu will stack and become one vertical column that is fully scrollable. If you use custom rendering, you will have to handle both of the above aspects yourself. Details for both methods can be found below: ```jsx render <h2>NavMenu.Columns</h2> ``` This component should be the outermost component of what is passed into `content`. It is used to provide styling for the dropdown container and the columns that go inside it. It does not require any additional props. ```jsx const items = [ { title: 'Dropdown menu', content: ( <NavMenu.Columns>Your NavMenu.Column components go here</NavMenu.Columns> ), }, ]; return <NavMenu items={items} />; ``` ```jsx render <h2>NavMenu.Column</h2> ``` This component should be a child of `NavMenu.Columns`. Each column that is a child of `NavMenu.Columns` will be a distinct column in the dropdown menu. Pass in a value for the `title` prop if you would like a bolded title to appear at the top of the column. `NavMenu.Column` can also accept an `href` prop for where the link will redirect to when clicked, or an `onClick` prop for a function that will be called when clicked. The children of this component will be displayed vertically; you can use `NavMenu.Item` as children to auto-format and style your input, or pass in your own custom renders to be displayed within the column. ```jsx const items = [ { title: 'Dropdown menu', content: ( <NavMenu.Columns> <NavMenu.Column title="Column Header"> Put NavMenu.Item components or custom rendering here </NavMenu.Column> <NavMenu.Column title="Column Header Link" href="/web/developers/overview" > Put NavMenu.Item components or custom rendering here </NavMenu.Column> <NavMenu.Column title="Column Header Button" onClick={() => { console.log('clicked'); }} > Put NavMenu.Item components or custom rendering here </NavMenu.Column> </NavMenu.Columns> ), }, ]; return <NavMenu items={items} />; ``` ```jsx render <h2>NavMenu.Item</h2> ``` This component should be a child of `NavMenu.Column`. Use this component to automatically style links in your dropdown that only have a title, description, and redirect link. Use the `title` prop for the title of the item, the `description` prop for the description, the `href` prop for where the link will redirect to when clicked, and the `onClick` prop for a function that will be called when clicked. If the `href` points to an external link, an icon will appear next to the title to signify that it will open in a new window. NOTE: each `NavMenu.Item` should have one of `href` or `onClick`, but not both. ```jsx const items = [ { title: 'Dropdown menu', content: ( <NavMenu.Columns> <NavMenu.Column> <NavMenu.Item title="Sample NavMenu.Item" description="Your description goes here" href="Your redirect link goes here" onClick={() => { 'Your onClick function goes here'; }} /> Put more NavMenu.Item components or custom rendering here </NavMenu.Column> Put more columns here </NavMenu.Columns> ), }, ]; return <NavMenu items={items} />; ``` ```jsx render <h2>Example with Helper Components</h2> ``` This is an example of how combining the helper components leads to a well-formatted dropdown menu: ```jsx live () => { const items = [ { title: 'Example using Helper Components', content: ( <NavMenu.Columns> <NavMenu.Column title="NavMenu.Column Title Prop"> <NavMenu.Item title="NavMenu.Item title prop" description="This is the NavMenu.Item description prop" href="#" /> <NavMenu.Item title="Sample onClick" onClick={() => console.log('onClick pressed')} description="A message will be logged to the console when this is clicked." /> </NavMenu.Column> <NavMenu.Column> <NavMenu.Item title="Column w/o title passed" description="This column's NavMenu.Column has no value for the title prop." href="#" /> <NavMenu.Item title="Open in new window" description="Since this will redirect to an external location, clicking this link will open it in a new window." href="https://abyss.uhc.com/" /> <NavMenu.Item title="Try shinking the screen until the header's search bar disappears" description="When the screen size is too small, the columns will combine into one." href="#" /> </NavMenu.Column> <NavMenu.Column title="Column 3 Title"> <NavMenu.Item title="See the divider to the left" description="When a column has a title (and it is not the first column), a vertical divider will appear between the previous column and this one." href="#" /> </NavMenu.Column> </NavMenu.Columns> ), }, ]; return ( <NavMenu items={items} css={{ 'abyss-nav-menu-container': { zIndex: 205 } }} /> ); }; ``` ```jsx render <h2>Custom Rendering</h2> ``` To render custom components at the base level, simply pass whatever you want to render in the `content` field within `items`: ```jsx live () => { const items = [ { title: 'Full Custom Rendering Example', content: ( <Layout.Stack space={25}> <IconSymbol icon="info" size="150" /> <Text>Custom rendering example</Text> </Layout.Stack> ), }, ]; return ( <NavMenu items={items} css={{ 'abyss-nav-menu-container': { zIndex: 204 } }} /> ); }; ``` <br /> You can also render custom components within `NavMenu.Column`, if you need to display something that doesn't fit the `NavMenu.Item` props: ```jsx live () => { const items = [ { title: 'Example using Helper Components', content: ( <NavMenu.Columns> <NavMenu.Column title="Sample Title"> <NavMenu.Item title="NavMenu.Item title prop" description="This is a NavMenu.Item" href="#" /> <Card> <IconSymbol icon="privacy_tip" size="$lg" /> <br /> This Card is a custom render (it's not a NavMenu.Item) </Card> </NavMenu.Column> </NavMenu.Columns> ), }, ]; return ( <NavMenu items={items} css={{ 'abyss-nav-menu-container': { zIndex: 203 } }} /> ); }; ``` ```jsx render <h2>Variant</h2> ``` Use the `variant` prop to change the appearance of the NavMenu. Possible values are `default` and `inverted`, and the default value is `default`. ```jsx live () => { const items = [ { title: 'Default Variant', href: '#' }, { title: 'Sample link 1', href: '#' }, ]; return <NavMenu items={items} />; }; ``` ```jsx live () => { const items = [ { title: 'Inverted Variant', href: '#' }, { title: 'Sample link 1', href: '#' }, ]; return <NavMenu items={items} variant="inverted" />; }; ``` ```jsx render <h2>Position</h2> ``` Use the `position` prop to set where the menu tabs will appear horizontally. The three options are `start`, `center`, and `end`, and the default value is `start`. ```jsx live () => { const items = [ { title: "'Start' position (Default)", href: '#' }, { title: 'Sample link', href: '#' }, ]; return <NavMenu items={items} />; }; ``` ```jsx live () => { const items = [ { title: "'Center' position", href: '#' }, { title: 'Sample link', href: '#' }, ]; return <NavMenu items={items} position="center" />; }; ``` ```jsx live () => { const items = [ { title: "'End' position", href: '#' }, { title: 'Sample link', href: '#' }, ]; return <NavMenu items={items} position="end" />; }; ``` ```jsx render <h2>Max NavMenu Width</h2> ``` Use the `maxNavWidth` prop to set the maximum width of the NavMenu component. ```jsx live () => { const navMenuItems = [ { title: 'Sample Link', href: '#' }, { title: 'Dropdown Menu', content: ( <NavMenu.Columns> <NavMenu.Column title="Section Title"> <NavMenu.Item title="HELLO" href="#" description="CSS-in-JS with best-in-class developer experience." /> <NavMenu.Item title="GOODBYE" href="#" description="Description goes here" /> </NavMenu.Column> <NavMenu.Column> <NavMenu.Item title="Sample Item" href="#" description="This is a description" /> </NavMenu.Column> <NavMenu.Column title="Other Section Title"> <NavMenu.Item title="Colors" href="#" description="Description goes here" /> <NavMenu.Item title="Colors" href="#" description="Description goes here" /> <NavMenu.Item title="Colors" href="#" description="Description goes here" /> </NavMenu.Column> </NavMenu.Columns> ), }, ]; return ( <NavMenu position="center" css={{ zIndex: '300' }} items={navMenuItems} maxNavWidth="744px" /> ); }; ``` ```jsx render <h2>PageHeader Component</h2> ``` If you would like to use this component as part of a page header, check out the [PageHeader](/web/ui/page-header) component, as it has integrated NavMenus inside of it already. Example of NavMenus inside PageHeader: ```jsx live () => { const topMenuItems = [ { title: 'Utility link', content: ( <NavMenu.Columns> <NavMenu.Column> <NavMenu.Item title="Test Link" description={ 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vitae lorem posuere augue volutpat tincidunt ut in odio. Sed non vehicula tellus.' } href="https://abyss.uhc.com/" /> <NavMenu.Item title="Test Link 2" description={ 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vitae lorem posuere augue volutpat tincidunt ut in odio. Sed non vehicula tellus.' } href="https://abyss.uhc.com/" /> </NavMenu.Column> </NavMenu.Columns> ), }, { title: 'Utility link 2', href: 'https://abyss.uhc.com/', }, { title: ( <Layout.Group space={0}> TrackIt <div style={{ display: 'flex', justifyContent: 'center', alignItems: 'center', height: '14px', width: '14px', borderRadius: '50%', border: 'solid 1px #FFAF1F', backgroundColor: '#FEF7E5', marginLeft: '4px', fontSize: '10px', fontWeight: '700', color: '#002677', }} > 8 </div> </Layout.Group> ), href: '#', }, { title: ( <Layout.Group space={0}> John <div style={{ display: 'flex', justifyContent: 'center', alignItems: 'center', height: '14px', width: '14px', borderRadius: '50%', border: 'solid 1px #002677', marginLeft: '4px', fontSize: '10px', fontWeight: '$bold', }} > <IconSymbol icon="person" size="$sm" /> </div> </Layout.Group> ), href: '#', }, ]; const bottomMenuItems = [ { title: 'Sample Link', href: '#' }, { title: 'Dropdown Menu', content: ( <NavMenu.Columns> <NavMenu.Column title="Section Title"> <NavMenu.Item title="HELLO" href="#" description="CSS-in-JS with best-in-class developer experience." /> <NavMenu.Item title="GOODBYE" href="#" description="Description goes here" /> </NavMenu.Column> <NavMenu.Column> <NavMenu.Item title="Sample Item" href="#" description="This is a description" /> </NavMenu.Column> <NavMenu.Column title="Other Section Title"> <NavMenu.Item title="Colors" href="#" description="Description goes here" /> <NavMenu.Item title="Colors" href="#" description="Description goes here" /> <NavMenu.Item title="Colors" href="#" description="Description goes here" /> </NavMenu.Column> </NavMenu.Columns> ), }, ]; return ( <React.Fragment> <PageHeader topMenuItems={topMenuItems} bottomMenuItems={bottomMenuItems} css={{ 'abyss-header-root': { zIndex: 210 } }} > <PageHeader.Toolbar space={10}> <SelectInput label="Profile Option 1" value="Test 1" options={[{ value: 'Test 1', label: 'Test 1' }]} /> <SelectInput label="Profile Option 2" value="Test 2" options={[{ value: 'Test 2', label: 'Test 2' }]} css={{ 'abyss-select-input-root': { marginTop: '0 !important', }, }} /> </PageHeader.Toolbar> </PageHeader> <Box color="$white" height="100px"> <br /> <Label>Your page content goes here</Label> </Box> </React.Fragment> ); }; ``` ```jsx render <h2>Disabled NavMenu.Item</h2> ``` Set the `isDisabled` prop to `true` to disable an individual NavMenu.Item. ```jsx live () => { const navMenuItems = [ { title: 'Dropdown Menu', content: ( <NavMenu.Columns> <NavMenu.Column title="Section Title"> <NavMenu.Item title="HELLO" href="#" description="CSS-in-JS with best-in-class developer experience." isDisabled /> <NavMenu.Item title="GOODBYE" href="#" description="Description goes here" /> </NavMenu.Column> <NavMenu.Column> <NavMenu.Item title="Sample onClick" onClick={() => console.log('onClick pressed')} description="A message will be logged to the console when this is clicked." /> </NavMenu.Column> </NavMenu.Columns> ), }, ]; return <NavMenu items={navMenuItems} />; }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={NavMenu} rows={[ { name: 'items', type: 'array[shape]', description: 'The items that will be displayed in the navigation menu', }, { name: 'variant', type: "'default' | 'inverted'", description: "The variant for the menu's appearance", }, { name: 'position', type: "'start' | 'center' | 'end'", description: 'Set the position of the menu items', }, { name: 'maxNavWidth', type: 'number', description: 'Set the maximum width of the NavMenu component', }, { name: 'children', type: 'React Node', description: 'The children element of the Navigation Menu', }, { name: 'headerHeight', type: 'number', description: 'The height of the header of the NavMenu component', }, ]} /> ``` ```jsx render <Docs.PropsTable of={NavMenuPrimitives.Provider} rows={[ { name: 'children', type: 'ReactNode', description: 'NavMenuPrimitive components', }, { name: 'positionViewportToTrigger', type: 'boolean | object', description: 'Aligns dropdown menu viewport to corresponding trigger element; takes in optional "minWidth"', }, { name: 'scrollState', type: 'object', description: 'Optional prop for applying custom configurations to the responsive horizontal scroll behavior; see useHorizontalScroll for more details', }, { name: 'seoMode', type: 'boolean', default: 'false', description: 'Optional prop to ensure all drop-down menu content is rendered at all times and available for SEO purposes. Refer to the SEO Mode section for more details', }, ]} /> ``` ```jsx render <Docs.PropsTable of={NavMenuPrimitives.Root} rows={[ { name: 'variant', type: "'default' | 'inverted'", description: "The variant for the menu's appearance", }, { name: 'position', type: "'start' | 'center' | 'end'", description: 'Set the position of the menu items', }, { name: 'maxNavWidth', type: 'number', description: 'Set the maximum width of the NavMenu component', }, { name: 'hasOverlay', type: 'boolean', default: 'false', description: 'Show overlay when set to true', }, { name: 'zIndex', type: 'number', default: 101, description: 'Value for making Navmenu outstand when overlay is shown', }, { name: 'enableOutsideScroll', type: 'boolean', description: 'Allows scrolling outside the NavMenu even when a NavMenu dropdown item is open', }, ]} /> ``` ```jsx render <Docs.PropsTable of={NavMenuPrimitives.RouterHeader} rows={[ { name: 'onClick', type: 'function', description: 'Callback fired when NavMenuPrimitives.RouterHeader is clicked', }, ]} /> ``` ```jsx render <Docs.PropsTable of={NavMenu.Columns} rows={[ { name: 'children', type: 'ReactNode', description: 'The content that will be displayed in the dropdown menu', }, ]} /> ``` ```jsx render <Docs.PropsTable of={NavMenu.Column} rows={[ { name: 'title', type: 'ReactNode', description: 'The title of the column', }, { name: 'onClick', type: 'function', description: 'Callback fired when NavMenu.Column is clicked', }, { name: 'href', type: 'string', description: 'The URL that the NavMenu.Column will redirect to when clicked', }, { name: 'columnCount', type: 'number', description: 'The number of columns present inside the parent NavMenu.Columns', }, { name: 'children', type: 'ReactNode', description: 'The content that will be displayed within the column', }, ]} /> ``` ```jsx render <Docs.PropsTable of={NavMenu.Item} rows={[ { name: 'title', type: 'ReactNode', description: 'The title of the item', }, { name: 'description', type: 'string', description: 'The description of the item', }, { name: 'href', type: 'string', description: 'The URL that the Item will redirect to when clicked', }, { name: 'isDisabled', type: 'boolean', default: 'false', description: 'The item is disabled when set to true', }, { name: 'isActive', type: 'boolean', default: 'false', description: 'Applies an active class to be targeted for custom styling (only available in NavMenuPrimitives.Item)', }, ]} /> ``` ```jsx render <Docs.PropsTable of={NavMenuPrimitives.Link} rows={[ { name: 'children', type: 'ReactNode', description: 'The content that will be displayed in the link', }, { name: 'onClick', type: 'function', description: 'Renders the link as a button and will be triggered when clicked', }, { name: 'href', type: 'string', description: 'The URL that the link will redirect to when clicked', }, { name: 'variant', type: '"default" | "inverted"', description: 'The variant for the link appearance', }, { name: 'asChild', type: 'boolean', description: 'Set to true when the link is a child of NavMenu.Item within the nav menu bar', }, ]} /> ``` ```jsx render <Docs.PropsTable of={NavMenu.Menu} rows={[ { name: 'title', type: 'ReactNode', description: 'The title of the menu', }, { name: 'content', type: 'ReactNode', description: 'The content of the menu', }, { name: 'variant', type: 'default | inverted', description: 'The variant of the menu', }, ]} /> ``` ```jsx render <Docs.PropsTable of={StateRouter.Routes} rows={[ { name: 'children', type: 'ReactNode', description: 'The children components to be rendered within the StateRoutes', }, { name: 'isAnimated', type: 'boolean', description: 'Enables swiping animation on navigation', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={NavMenu} rows={[ { name: 'nav-menu-portal', description: 'NavMenu portal (only available when using seoMode)', }, { name: 'nav-menu-root', description: 'NavMenu root element', }, { name: 'nav-menu-container', description: 'NavMenu root container', }, { name: 'nav-menu-list', description: 'List of items on the main NavMenu bar', }, { name: 'nav-menu-link-root', description: 'Main NavMenu bar link items root container', }, { name: 'nav-menu-link', description: 'Main NavMenu bar items with an href (no dropdown menu)', }, { name: 'nav-menu-viewport-container', description: 'Main NavMenu dropdown viewport container', }, { name: 'nav-menu-viewport', description: 'Main NavMenu dropdown viewport', }, { name: 'nav-menu-menu', description: 'Main NavMenu bar items with content instead of href (has dropdown menu)', }, { name: 'nav-menu-menu-active', description: 'Main NavMenu bar items with isActive applied (only available in NavMenuPrimitives.Item)', }, { name: 'nav-menu-menu-item', description: 'NavMenu menu item content container', }, { name: 'nav-menu-menu-trigger', description: 'NavMenu menu item trigger', }, { name: 'nav-menu-menu-trigger-icon-container', description: 'NavMenu menu item trigger icon container', }, { name: 'nav-menu-menu-trigger-icon', description: 'NavMenu menu item trigger icon', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={NavMenu.Columns} rows={[ { name: 'nav-menu-columns-root', description: 'NavMenu.Columns root element', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={NavMenu.Menu} rows={[ { name: 'nav-menu-menu', description: 'NavMenu.Menu element', }, { name: 'nav-menu-menu-item', description: 'NavMenu.Menu item', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={NavMenu.Column} rows={[ { name: 'nav-menu-column-root', description: 'NavMenu.Column root element', }, { name: 'nav-menu-column', description: 'NavMenu.Column column', }, { name: 'nav-menu-column-title', description: 'Title of the column', }, { name: 'nav-menu-column-list', description: 'Column list', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={NavMenu.Item} rows={[ { name: 'nav-menu-item-root', description: 'NavMenu.Item root element', }, { name: 'nav-menu-item-title', description: 'Title of the item', }, { name: 'nav-menu-item-link-icon', description: '"Open in new window" icon that appears when the href is an external link', }, { name: 'nav-menu-item-description', description: 'Description of the item', }, ]} /> ``` </Tab> <Tab label="Accessibility"> <h3> Reduced Motion </h3> Animations and transitions that have been changed when a user has `prefers-reduced-motion` set to `reduced`: - Transition upon expand/collapse is removed <h3> Implementation </h3> The example below showcases a complex menu that includes all the right accessibility settings ```jsx live () => { const DropdownMenuContent2 = () => ( <NavMenuPrimitives.Columns> <NavMenuPrimitives.Column title="Medicare plan types"> <NavMenuPrimitives.MenuItem title="Medicare advantage plans" href="https://www.uhc.com/medicare/shop/medicare-advantage-plans.html" /> <NavMenuPrimitives.MenuItem title="Medicare Supplement plans" href="https://www.uhc.com/medicare/shop/medicare-supplement-plans.html" /> <NavMenuPrimitives.MenuItem title="Medicare prescription drug plans" href="https://www.uhc.com/medicare/shop/prescription-drug-plans.html" /> <NavMenuPrimitives.MenuItem title="Dual-Special Needs plan (D-SNP)" href="https://www.uhc.com/medicare/shop/dual-special-needs-plans.html" /> <li> <Link after={<IconSymbol icon="chevron_right" size={20} />} href="https://www.uhc.com/medicare/shop.html?WT.mc_id=8031053" > Shop all Medicare plans </Link> </li> </NavMenuPrimitives.Column> <NavMenuPrimitives.Column title="Get help with choosing a plan"> <NavMenuPrimitives.MenuItem title="Help me find a plan" href="https://www.uhc.com/medicare/plan-recommendation-engine.html" /> <NavMenuPrimitives.MenuItem title="Estimate drug costs" href="https://www.uhc.com/medicare/health-plans/estimate-drug-costs.html" /> <NavMenuPrimitives.MenuItem title="Search for a pharmacy" href="https://www.uhc.com/medicare/health-plans/aarp-pharmacy.html" /> <NavMenuPrimitives.MenuItem title="Find a doctor" href="https://connect.werally.com/county-plan-selection/uhc.mnr/zip" /> <NavMenuPrimitives.MenuItem title="Find a dentist" href="https://connect.werally.com/plan-location" /> <NavMenuPrimitives.MenuItem title="Medicare overview" href="https://www.uhc.com/medicare/medicare-education.html" /> </NavMenuPrimitives.Column> <NavMenuPrimitives.Column> <li> <Layout.Stack alignItems="left"> <h6 aria-level="2">Find Medicare plans near you</h6> <TextInput label="Enter ZIP code" isClearable /> <Button type="submit" style={{ marginTop: 15 }}> Find plans </Button> <Divider /> <h6 aria-level="2">Not sure where to start?</h6> <p> Answer a few questions and get plan recommendations based on the information you provide. <br /> <Link after={<IconSymbol icon="chevron_right" size={20} />} href="https://www.uhc.com/medicare/plan-recommendation-engine.html" > Get started </Link> </p> </Layout.Stack> </li> </NavMenuPrimitives.Column> </NavMenuPrimitives.Columns> ); const DropdownMenuContent = () => ( <NavMenuPrimitives.Columns> <NavMenuPrimitives.Column title="Plan types"> <NavMenuPrimitives.MenuItem title="Short term plans" href="https://www.uhc.com/individuals-families/short-term-health-insurance" /> <NavMenuPrimitives.MenuItem title="ACA marketplace plans" href="https://www.uhc.com/individuals-families/aca-marketplace" /> <NavMenuPrimitives.MenuItem title="Plans through work" href="https://www.uhc.com/individuals-families/health-plans-through-work" /> <NavMenuPrimitives.MenuItem title="All health insurance plans" href="https://www.uhc.com/individuals-families" /> </NavMenuPrimitives.Column> <NavMenuPrimitives.Column title="Understanding health insurance"> <NavMenuPrimitives.MenuItem title="Short term vs. ACA plans" href="https://www.uhc.com/understanding-health-insurance/types-of-health-insurance/aca-vs-short-term" /> <NavMenuPrimitives.MenuItem title="Open enrollment" href="https://www.uhc.com/understanding-health-insurance/open-enrollment" /> <NavMenuPrimitives.MenuItem title="Qualifying life events" href="https://www.uhc.com/understanding-health-insurance/open-enrollment/qualifying-life-events" /> <NavMenuPrimitives.MenuItem title="Medicaid renewal" href="https://www.uhc.com/understanding-health-insurance/medicaid-renewal-redetermination-coverage-options" /> </NavMenuPrimitives.Column> <NavMenuPrimitives.Column title="Need help finding a plan?"> <NavMenuPrimitives.MenuItem title="Find your plan" description="Answer a few questions to see which insurance options may be available for you." href="https://www.uhc.com/insurance-plan-finder" /> </NavMenuPrimitives.Column> </NavMenuPrimitives.Columns> ); const DropdownMenuContent3 = () => ( <NavMenuPrimitives.Columns> <NavMenuPrimitives.Column title=""> <NavMenuPrimitives.MenuItem title="Small business" href="https://www.uhc.com/employer/small-business" description="Learn more about our group health insurance plans for small business and get a quote." /> </NavMenuPrimitives.Column> <NavMenuPrimitives.Column title=""> <NavMenuPrimitives.MenuItem title="Large organizations" href="https://www.uhc.com/employer/small-business" description="Learn more about our products for National Accounts, public sector and group retiree solutions." /> </NavMenuPrimitives.Column> <NavMenuPrimitives.Column title=""> <NavMenuPrimitives.MenuItem title="All group plans for employers" href="https://www.uhc.com/employer/small-business" description="Explore all of our group health insurance plans and benefits." /> </NavMenuPrimitives.Column> </NavMenuPrimitives.Columns> ); return ( <NavMenuPrimitives.Provider> <NavMenuPrimitives.Root zIndex={103} hasOverlay enableOutsideScroll={false} > <NavMenuPrimitives.List> <NavMenuPrimitives.Item> <NavMenuPrimitives.Trigger>Medicare</NavMenuPrimitives.Trigger> <NavMenuPrimitives.Content> <DropdownMenuContent2 /> </NavMenuPrimitives.Content> </NavMenuPrimitives.Item> <NavMenuPrimitives.Item> <NavMenuPrimitives.Content> <DropdownMenuContent /> </NavMenuPrimitives.Content> <NavMenuPrimitives.Trigger> Health Insurance Plans </NavMenuPrimitives.Trigger> </NavMenuPrimitives.Item> <NavMenuPrimitives.Item> <NavMenuPrimitives.Trigger> Group plans for employers </NavMenuPrimitives.Trigger> <NavMenuPrimitives.Content> <DropdownMenuContent3 /> </NavMenuPrimitives.Content> </NavMenuPrimitives.Item> <NavMenuPrimitives.Link href="https://www.uhc.com/shop-online-health-insurance-plans"> Shop all plans </NavMenuPrimitives.Link> </NavMenuPrimitives.List> <NavMenuPrimitives.Viewport /> </NavMenuPrimitives.Root> </NavMenuPrimitives.Provider> ); }; ``` ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Tab', description: 'Moves focus to the next focusable element.', }, { name: 'Enter', description: 'Redirects to the link if the menu bar item is a redirect, or opens the relevant dropdown menu if the item has one.', }, { name: 'Space', description: 'If focus on a menu bar item with a dropdown, opens the relevant dropdown menu.', }, { name: 'Left Arrow', description: 'Focuses the previous menu bar item.', }, { name: 'Up Arrow', description: 'Focuses the previous menu bar item.', }, { name: 'Right Arrow', description: 'Focuses the next menu bar item.', }, { name: 'Down Arrow', description: 'Focuses the next menu bar item. If focus is on an open menu bar item, moves focus into its dropdown menu instead.', }, { name: 'Escape', description: 'Closes open dropdown menu and moves focus to its menu bar item.', }, { name: 'Home', description: 'Moves focus to the first item in the menu.', }, { name: 'End', description: 'Moves focus to the last item in the menu.', }, ]} /> ``` </Tab> --- id: number-input-v2 category: Forms title: V2NumberInput description: Allows users to enter a number into a UI. design: https://www.figma.com/design/a8XbEI7AmNb94mOBgYUB7y/v1.73.0-Web-Abyss-Global%E2%80%A8Component-Library?node-id=8243-444 subDirectory: NumberInput/v2 sourceIsTS: true --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="NumberInput"></Docs.V2MigrationBanner> ``` ```jsx import { V2NumberInput } from '@uhg-abyss/web/ui/NumberInput'; ``` ```jsx sandbox { component: 'V2NumberInput', inputs: [ { prop: 'step', type: 'number', }, { prop: 'minValue', type: 'number', defaultValue: '0' }, { prop: 'subText', type: 'string', }, { prop: 'maxValue', type: 'number', defaultValue: '10' }, { prop: 'hideLabel', type: 'boolean', }, { prop: 'isDisabled', type: 'boolean', }, { prop: 'isRequired', type: 'boolean', }, { prop: 'stepperOnly', type: 'boolean', }, ] } () => { const [value, setValue] = useState('5'); return ( <V2NumberInput label="NumberInput Sandbox" value={value} onChange={(e) => setValue(e)} /> ); }; ``` ## useForm (recommended) Using the `useFormV2` hook lets the DOM handle form data. ```jsx render <Docs.FormMessage /> ``` <br /> ```jsx render <Docs.FormDisclaimer /> ``` ```jsx live () => { const form = useFormV2({ defaultValues: { numberForm: '2', }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2NumberInput label="NumberInput useForm" model="numberForm" validators={{ required: true }} /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [value, setValue] = useState('5'); const onSubmit = () => { console.log('value', value); }; return ( <React.Fragment> <V2NumberInput label="NumberInput useState" value={value} onChange={(e) => setValue(e)} /> <V2Button onClick={onSubmit} css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </React.Fragment> ); }; ``` ## Display properties ### Label Use the `label` prop to display a label above the input. To hide the input label set `hideLabel` to `true`. Use `isRequired` for further customization. Note: If using `useForm`, do not use `isRequired`. The same functionality can be achieved with `required: true` in `validators`. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2({ defaultValues: { 'custom-label': '', 'custom-hidden-label': '', }, }); return ( <V2FormProvider state={form}> <FormSpacing> <V2NumberInput label="Custom Label" model="custom-label" /> <V2NumberInput label="Hidden Label" model="custom-hidden-label" hideLabel /> </FormSpacing> </V2FormProvider> ); }; ``` ### Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip-v2) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip-v2) or a [Popover](/web/ui/popover-v2). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip-v2/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); return ( <V2FormProvider state={form}> <FormSpacing> <V2NumberInput label="Default Helper" helper="This is a tooltip" model="helper-tooltip" /> <V2NumberInput label="Custom Helper" helper={ <V2Popover title="Custom Helper" content="This is a popover with a custom icon" > <IconSymbol icon="help" variant="outlined" color="$success1" size="$sm" /> </V2Popover> } model="helper-custom" validators={{ required: true }} /> </FormSpacing> </V2FormProvider> ); }; ``` ### Subtext Use the `subText` prop to display helpful information related to the input field. The prop accepts either a string or an object of the form: ```ts { text: string; position: 'above' | 'below'; } ``` The `position` property determines where the subtext will be displayed in relation to the input field. The default value is `'below'`. Where appropriate, use it for detailing the [increment/step](#step-value) value, as shown in the example below. When doing so, avoid using abbreviations like "Inc." or "Dec." and instead use full descriptive terms like "increment" or "decrement". ```jsx live () => { const [value, setValue] = useState('5'); const stepAmount = 2; return ( <V2NumberInput step={stepAmount} label="Sub Text" value={value} onChange={(value) => setValue(value)} subText={`Increment Amount: ${stepAmount}`} /> ); }; ``` ### Stepper only Use the `stepperOnly` prop to disable the input field and only allow value changes through the increment and decrement buttons. The default is `false`. Note: When using `stepperOnly`, the input field is still accessible through keyboard navigation. ```jsx live () => { const [value, setValue] = useState('0'); return ( <V2NumberInput label="Stepper Only" value={value} onChange={(e) => setValue(e)} stepperOnly /> ); }; ``` ### Width Use the `width` prop to set the width of the number input field. The default value is `48px`. A width value should be chosen to allow the maximum value to be fully visible, but the default behavior is an ellipsis displayed to signify overflow. ```jsx live () => { const [value, setValue] = useState('50000'); return ( <V2NumberInput label="Width" value={value} onChange={(e) => setValue(e)} width="100px" /> ); }; ``` ## Validation ### Validators (useForm) ```jsx render <Docs.FormCompatibilityWidget useForm /> ``` Use the `validators` prop to display a custom error below the number input field or do other validation when using `useFormV2`. Note: The default error message when `required` is `true` is minimally acceptable for accessibility. It is highly recommended to customize it to be more specific to the use of the field and form. ```jsx live () => { const form = useFormV2({ defaultValues: { validationForm: '', }, }); return ( <V2FormProvider state={form}> <V2NumberInput label="Validators" model="validationForm" validators={{ required: 'This field is required' }} /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ### Error message ```jsx render <Docs.FormCompatibilityWidget useState /> ``` Use the `errorMessage` prop to display a custom error message below the input field when using `useState`. ```jsx live () => { const [value, setValue] = useState('0'); return ( <V2NumberInput label="Custom Error" value={value} onChange={(e) => setValue(e)} errorMessage="This is an error message" /> ); }; ``` ### Success message ```jsx render <Docs.FormCompatibilityWidget useForm useState /> ``` Use the `successMessage` prop to display a custom success message below the input field. To provide a single success message across all form input components using `useFormV2`/`V2FormProvider`, you can provide `successMessage` to `V2FormProvider` as shown [here](/web/ui/form-provider-v2#successmessage). ```jsx live () => { const form = useFormV2({ defaultValues: { numberSuccessForm: '5', }, }); return ( <V2FormProvider state={form}> <V2NumberInput label="Custom Success" model="numberSuccessForm" successMessage="A number has been selected" validators={{ required: 'Please select a number' }} /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ### Highlighted Use the `highlighted` prop to enable the background color for the number input field. ```jsx live () => { const [value, setValue] = useState('88'); return ( <V2NumberInput label="Highlighted" value={value} onChange={(e) => setValue(e)} highlighted /> ); }; ``` ### Min and max values Use the `minValue` and `maxValue` props to apply min/max limits to the number input field. The default minValue is `-9007199254740991` and maxValue is `9007199254740991`. When minValue and maxValue are provided, input will be validated against the min/max values upon blur. For example, if the maxValue is 5, and the user types 7, 5 will replace 7. ```jsx live () => { const [value, setValue] = useState('0'); const onSubmit = () => { console.log('value', value); }; return ( <V2NumberInput label="Min/Max Value" value={value} onChange={(e) => setValue(e)} minValue={-5} maxValue={5} /> ); }; ``` ## Step value Use the `step` prop to increase and decrease the value by the given step. The default value is set to `1`. ```jsx live () => { const [value, setValue] = useState('0'); const onSubmit = () => { console.log('value', value); }; return ( <React.Fragment> <V2NumberInput label="Step Value" value={value} onChange={(e) => setValue(e)} step={4} subText="Step value of 4" /> <V2Button onClick={onSubmit} css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </React.Fragment> ); }; ``` ## Masks ### Mask config Use the `maskConfig` prop to pass a masking configuration to the number input field. The default value for `decimalScale` is `0`. We use <ExitLink href="https://s-yadav.github.io/react-number-format/docs/intro">react-number-format</ExitLink> internally for mask configuration. Please visit the provided link for more details on the available options. ```jsx live () => { const [value, setValue] = useState('0.05'); const onSubmit = () => { console.log('value', value); }; return ( <React.Fragment> <V2NumberInput label="Mask Config" value={value} onChange={(e) => setValue(e)} maskConfig={{ decimalScale: 2, }} width={'80px'} /> <V2Button onClick={onSubmit} css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </React.Fragment> ); }; ``` ### Decimal step value Use the `decimalScale` prop within `maskConfig` and set to a value greater than `0` to allow decimal values within the number input field. The `step` prop can also be used to increase/decrease by decimal values. ```jsx live () => { const [value, setValue] = useState('0.75'); const onSubmit = () => { console.log('value', value); }; return ( <React.Fragment> <V2NumberInput label="Decimal Step" value={value} onChange={(e) => setValue(e)} maskConfig={{ decimalScale: 2, //allow decimals and define limits to decimal scale fixedDecimalScale: true, // add 0s to match given decimalScale }} step={0.05} width={'80px'} /> <V2Button onClick={onSubmit} css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </React.Fragment> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2NumberInput" propTypeName="V2NumberInputProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2ClassesTable title="V2NumberInput" classes={[NumberInputClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> <h2>NumberInput is a spinbutton</h2> NumberInput is an implementation of the HTML5 <ExitLink href="https://www.w3schools.com/tags/att_input_type_number.asp">`<input type=”number”>`</ExitLink> and WAI-ARIA <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/">spinbutton pattern</ExitLink> . <h2>Spinbutton “single field” implementation</h2> Standard spinbutton functionality (both in HTML5 and WAI-ARIA) is provided by the up and down arrows. This makes the increment and decrement buttons redundant for keyboard operation. This same approach is applied in NumberInput. This is why in NumberInput the visible [-] and [+] do not receive keyboard focus. If they received focus the field would: - become a grouping of one field and two buttons -- making it a non-standard for spinbutton - more cumbersome to use -- adding extra tab stops for unnecessary buttons - require lengthier announcements for grouping and value <h2>Button behavior on click: set focus to field</h2> The buttons do remain clickable/tappable for mouse/touch operation. When selected, NumberInput sets focus to the field to provide missing context to the announced button. This provides the expected behavior for HTML5 type=”input” when clicking the same control onHover. It also improves on the <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/examples/datepicker-spinbuttons/">WAI-ARIA example</ExitLink> that only announces the button and provides no context for what it controls. A known potential issue with this implementation is that the full description of the field is announced on each click which can be lengthy. This should not be a significant issue to any sighted mouse users that also use screen readers who choose to use them since new clicks interrupt announcements of previous ones. ```jsx live () => { const form = useFormV2({ defaultValues: { numberErrorForm: '', }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2NumberInput label="Ice cream scoops" model="numberForm" minValue={0} maxValue={5} helper={ <V2Popover title="Do not want any ice cream?" content="Enter 0 (zero)" > <IconSymbol icon="help" variant="outlined" color="$success1" size="$sm" title="Help" isScreenReadable={true} /> </V2Popover> } subText="5 scoops maximum" validators={{ required: true }} /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ```jsx live () => { const form = useFormV2({ defaultValues: { numberErrorForm: '', }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2NumberInput label="Number of toppings" model="numberForm" stepperOnly={true} minValue={0} maxValue={5} helper={ <V2Popover title="Do not want any toppings?" content="Enter 0 (zero)"> <IconSymbol icon="help" variant="outlined" color="$success1" size="$sm" title="Help" isScreenReadable={true} /> </V2Popover> } subText="5 toppings maximum" validators={{ required: true }} /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` <h2>Screen reader operation (errors)</h2> VoiceOver (MacOS Sonoma 14.4.1) announces "50%" when focus is (re-)set to the field. Using up/down arrows announces correct current value. Exiting and returning to field will still announce "50%" on focus. This appears to be a bug in VoiceOver interpretation of the field's value. This fails in WAI-ARIA <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/examples/datepicker-spinbuttons/">Date Picker Spin Button Example</ExitLink> (for the year field). Adding aria-valuenow or aria-valuetext has no effect on the announcement. As of this writing (May 2024) There is little information found about how to address this. ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Up Arrow', description: 'Increment value', }, { name: 'Down Arrow', description: 'Decrement value', }, { name: 'Left Arrow', description: 'Move to the previous character in the input field', }, { name: 'Right Arrow', description: 'Move to the next character in the input field', }, { name: 'Page Up', description: 'Currently not supported', }, { name: 'Page Down', description: 'Currently not supported', }, ]} /> ``` </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={NumberInput} keys={['numberInputV2']} /> ``` </Tab> --- id: number-input category: Forms title: NumberInput description: Allows users to enter a number into a UI. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=27439-98953 subDirectory: NumberInput/v1 --- <Tab label="Overview"> ```jsx import { NumberInput } from '@uhg-abyss/web/ui/NumberInput'; ``` ```jsx sandbox { component: 'NumberInput', inputs: [ { prop: 'errorMessage', type: 'string', }, { prop: 'stepValue', type: 'number', }, { prop: 'minValue', type: 'number', defaultValue: '0' }, { prop: 'maxValue', type: 'number', defaultValue: '10' }, { prop: 'hideLabel', type: 'boolean', }, { prop: 'isDisabled', type: 'boolean', }, ] } () => { const [value, setValue] = useState('5'); return ( <NumberInput label="NumberInput Sandbox" value={value} onChange={(e) => setValue(e)} /> ); }; ``` ## useForm (recommended) Using the `useForm` hook for handling NumberInput lets the DOM handle form data. ```jsx live () => { const form = useForm({ defaultValues: { numberForm: '2', }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <NumberInput label="NumberInput useForm" model="numberForm" validators={{ required: true }} /> <Button type="submit" style={{ marginTop: 15 }}> Submit </Button> </FormProvider> ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [value, setValue] = useState('5'); const onSubmit = () => { console.log('value', value); }; return ( <React.Fragment> <NumberInput label="NumberInput useState" value={value} onChange={(e) => setValue(e)} /> <Button onClick={onSubmit} style={{ marginTop: 15 }}> Submit </Button> </React.Fragment> ); }; ``` ## Step value Use the `stepValue` prop to increase and decrease the value by given step. The default value is set to `1` ```jsx live () => { const [value, setValue] = useState('0'); const onSubmit = () => { console.log('value', value); }; return ( <React.Fragment> <NumberInput label="Step Value" value={value} onChange={(e) => setValue(e)} stepValue={4} /> <Button onClick={onSubmit} style={{ marginTop: 15 }}> Submit </Button> </React.Fragment> ); }; ``` ## Subtext Use the `subText` prop to provide additional context or details below the input field. Where appropriate, use it for detailing the [increment/stepValue](#step-value) value, as shown in the example below. When doing so, avoid using abbreviations like "Inc." or "Dec." and instead use full descriptive terms like "increment" or "decrement". ```jsx live () => { const [value, setValue] = useState('5'); const stepAmount = 2; return ( <NumberInput stepValue={stepAmount} label="Sub Text" value={value} onChange={(value) => setValue(value)} subText={`Increment Amount: ${stepAmount}`} /> ); }; ``` ## Min and max values Use the `minValue` and `maxValue` props to apply min/max limits to the number input field. The default minValue is `-9007199254740991` and maxValue is `9007199254740991`. Note: When minValue and maxValue are provided, input will be validated against these min/max values on blur or on hitting the enter key. For example, if the maxValue is 5, and the user types 7, 5 will replace 7 in the box after hitting enter or unfocusing the element. ```jsx live () => { const [value, setValue] = useState('0'); const onSubmit = () => { console.log('value', value); }; return ( <React.Fragment> <NumberInput label="Min/Max Value" value={value} onChange={(e) => setValue(e)} minValue={-5} maxValue={5} /> </React.Fragment> ); }; ``` ## Validation Use the `validators` prop to display a custom error message below the number input field. ```jsx live () => { const form = useForm({ defaultValues: { numberErrorForm: '', }, }); return ( <FormProvider state={form}> <NumberInput label="Custom Error" model="numberErrorForm" validators={{ required: 'Custom Error Message' }} /> <Button type="submit" style={{ marginTop: 15 }}> Submit </Button> </FormProvider> ); }; ``` ## Mask config Use the `maskConfig` prop to pass a masking configuration to the number input field. The default value for `thousandSeparator` is `,` and `decimalScale` is `0`. Please visit this <ExitLink href="https://github.com/s-yadav/react-number-format/blob/master/documentation/v4.md">link</ExitLink> for documentation on additional configuration settings. ```jsx live () => { const [value, setValue] = useState('0.05'); const onSubmit = () => { console.log('value', value); }; return ( <React.Fragment> <NumberInput label="Mask Config" value={value} onChange={(e) => setValue(e)} maskConfig={{ decimalScale: 2, }} /> <Button onClick={onSubmit} style={{ marginTop: 15 }}> Submit </Button> </React.Fragment> ); }; ``` ## Decimal step value Use the `decimalScale` prop within `maskConfig` and set to a value greater than `0` to allow decimal values within the number input field. The `stepValue` prop can also be used to increase/decrease by decimal values. ```jsx live () => { const [value, setValue] = useState('0.75'); const onSubmit = () => { console.log('value', value); }; return ( <React.Fragment> <NumberInput label="Decimal Step" value={value} onChange={(e) => setValue(e)} maskConfig={{ decimalScale: 2, //allow decimals and define limits to decimal scale fixedDecimalScale: true, // add 0s to match given decimalScale }} stepValue={0.05} /> <Button onClick={onSubmit} style={{ marginTop: 15 }}> Submit </Button> </React.Fragment> ); }; ``` ## Label Use the `label` prop to display a label above the input. To hide the input label set `hideLabel` to `true`. ```jsx live () => { const form = useForm({ defaultValues: { 'custom-label': '', 'custom-hidden-label': '', }, }); return ( <FormProvider state={form}> <NumberInput label="Custom Label" model="custom-label" /> <NumberInput label="Hidden Label" model="custom-hidden-label" hideLabel /> </FormProvider> ); }; ``` ## Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip) or a [Popover](/web/ui/popover). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <NumberInput label="Default Helper" helper="This is a tooltip" model="helper-tooltip" /> <NumberInput label="Custom Helper" helper={ <Popover title="Custom Helper" content="This is a popover with a custom icon" > <IconSymbol icon="help" variant="outlined" color="$success1" size="$sm" /> </Popover> } model="helper-custom" validators={{ required: true }} /> </FormProvider> ); }; ``` ## Descriptors display Use the `descriptorsDisplay` prop to set the orientation of the error message and subtext descriptor content. Available variants include 'column' and 'row'. The default is set to 'row'. Use the [FormProvider](/web/ui/form-provider#descriptors-display) and `descriptorsDisplay` to set the descriptors orientation across an entire form. Note: The errorMessage prop does not work with useForm and is only applicable within our form input components when useState is being utilized. See the [useForm Docs](/web/hooks/use-form#set-error) for example use cases with useForm. ```jsx live () => { const [value, setValue] = useState('0'); const onSubmit = () => { console.log('value', value); }; return ( <React.Fragment> <NumberInput value={value} onChange={(e) => setValue(e)} stepValue={4} label="Descriptors Display" errorMessage="Error Message" descriptorsDisplay="column" /> <Button onClick={onSubmit} style={{ marginTop: 15 }}> Submit </Button> </React.Fragment> ); }; ``` ## Highlighted Use the `highlighted` prop to enable the background color for the number input field. ```jsx live () => { const [value, setValue] = useState('888'); return ( <NumberInput label="Highlighted" value={value} onChange={(e) => setValue(e)} highlighted /> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={NumberInput} rows={[ { name: 'label', type: 'string', description: 'Label for input field', }, { name: 'helper', type: 'node | string', description: 'Helper element next to label', }, { name: 'placeholder', type: 'string', description: 'Short description displayed in the input before the user enters a value', }, { name: 'isDisabled', type: 'boolean', description: 'Flag to enable/disable the input. If true, the input will be disabled', }, { name: 'value', type: 'string', description: 'Value of the number input', }, { name: 'validators', type: 'object', description: 'Set rules for the input field to be valid', }, { name: 'onChange', type: 'function', description: 'Callback fired every time the value changes', }, { name: 'onFocus', type: 'function', description: 'Callback fired every time the component is focused', }, { name: 'onBlur', type: 'function', description: 'Callback fired every time the component is unfocused', }, { name: 'onKeyDown', type: 'function', description: 'Callback fired every time a key is pressed while focused in the component', }, { name: 'onPaste', type: 'function', description: 'Callback fired every time something is pasted into the component', }, { name: 'model', type: 'string', description: 'Unique identifier used for FormProvider', }, { name: 'maskConfig', type: 'shape', description: 'Set configs for mask utilized by the react-number-format library', }, { name: 'errorMessage', type: 'string', description: 'Error message to be displayed below number input field', }, { name: 'subText', type: 'string', description: 'Set the text displayed below input field', }, { name: 'descriptorsDisplay', type: '"row" | "column"', description: 'Set the orientation of descriptor content located below number input field', }, { name: 'hideLabel', type: 'boolean', description: 'Flag to show or hide label', }, { name: 'stepValue', type: 'number', description: 'Step value for number input', }, { name: 'minValue', type: 'number', description: 'Minimum value for number input', }, { name: 'maxValue', type: 'number', description: 'Maximum value for number input', }, { name: 'highlighted', type: 'boolean', description: 'Render input with highlighted background', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={NumberInput} rows={[ { name: 'number-input-root', description: 'NumberInput root element', }, { name: 'number-input-label', description: 'FormInput label', }, { name: 'number-input-wrapper', description: 'Wrapper For Number Input', }, { name: 'number-input-descriptors', description: 'Descriptor for FormInput', }, { name: 'number-input-span', description: 'Hidden span element for auto width adjustment', }, { name: 'number-picker-input', description: 'Number Input Element', }, { name: 'number-input-decrement-button', description: 'Number Input Decrement Button Element', }, { name: 'number-input-increment-button', description: 'Number Input Increment Button Element', }, ]} /> ``` </Tab> <Tab label="Accessibility"> <h2>NumberInput is a spinbutton</h2> NumberInput is an implementation of the HTML5 <ExitLink href="https://www.w3schools.com/tags/att_input_type_number.asp">`<input type=”number”>`</ExitLink> and WAI-ARIA <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/">spinbutton pattern</ExitLink> . <h2>Spinbutton “single field” implementation</h2> Standard spinbutton functionality (both in HTML5 and WAI-ARIA) is provided by the up and down arrows. This makes the increment and decrement buttons redundant for keyboard operation. This same approach is applied in NumberInput. <b> This is why in NumberInput the visible [-] and [+] do not receive keyboard focus. </b> <br /> <br /> If they received focus the field would: <li> become a grouping of one field and two buttons -- making it a non-standard for spinbutton </li> <li> more cumbersome to use -- adding extra tab stops for unnecessary buttons </li> <li>require lengthier announcements for grouping and value</li> <h2>Button behavior on click: set focus to field</h2> The buttons do remain clickable/tappable for mouse/touch operation. When selected, NumberInput sets focus to the field to provide missing context to the announced button. This provides the expected behavior for HTML5 type=”input” when clicking the same control onHover. It also improves on the <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/examples/datepicker-spinbuttons/">WAI-ARIA example</ExitLink> that only announces the button and provides no context for what it controls. A known potential issue with this implementation is that the full description of the field is announced on each click which can be lengthy. This should not be a significant issue to any sighted mouse users that also use screen readers who choose to use them since new clicks interrupt announcements of previous ones. ```jsx live () => { const form = useForm({ defaultValues: { numberErrorForm: '', }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <NumberInput label="Ice cream scoops" model="numberForm" minValue={0} maxValue={5} helper={ <Popover title="Do not want any ice cream?" content="Enter 0 (zero)"> <IconSymbol icon="help" variant="outlined" color="$success1" size="$sm" title="Help" isScreenReadable={true} /> </Popover> } model="helper-custom" subText="Maximum scoops: 5." validators={{ required: true }} /> <Button type="submit" style={{ marginTop: 15 }}> Submit </Button> </FormProvider> ); }; ``` <h2>Screen reader operation (errors)</h2> VoiceOver (MacOS Sonoma 14.4.1) announces "50%" when focus is (re-)set to the field. Using up/down arrows announces correct current value. Exiting and returning to field will still announce "50%" on focus. This appears to be a bug in VoiceOver interpretation of the field's value. This fails in WAI-ARIA <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/examples/datepicker-spinbuttons/">Date Picker Spin Button Example</ExitLink> (for the year field). Adding aria-valuenow or aria-valuetext has no effect on the announcement. As of this writing (May 2024) There is little information found about how to address this. ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Up Arrow', description: 'Increment value', }, { name: 'Down Arrow', description: 'Decrement value', }, { name: 'Home', description: 'Start of text field (currently does not set min value)', }, { name: 'End', description: 'End of text field (currently does not set max. value)', }, { name: 'Page Up', description: 'Currently not supported', }, { name: 'Page Down', description: 'Currently not supported', }, ]} /> ``` </Tab> --- id: overlay-provider category: Providers title: OverlayProvider description: Adds a React Context to support overlay functionality to Abyss modals, drawers, etc. --- <Tab label="Overview"> ```jsx import { OverlayProvider } from '@uhg-abyss/web/ui/OverlayProvider'; ``` ## Usage Applications must be wrapped in an OverlayProvider so that it can be hidden from screen readers when an overlay opens. ```jsx <OverlayProvider> <App>{children}</App> </OverlayProvider> ``` ## Modal example `OverlayProvider` is used to support components such as Modal. Use the `useOverlay` hook to support state management of the overlay. Find additional resources on our overlay hook in [useOverlay](/web/hooks/use-overlay). ```jsx live () => { const modal = useOverlay('data-modal'); const { data } = modal.getState(); return ( <React.Fragment> <Button onClick={() => modal.open({ firstName: 'John', lastName: 'Doe' })} aria-haspopup="dialog" > Toggle Modal </Button> <Modal title="Modal Example" model="data-modal"> <Modal.Section> <p>First Name: {data && data.firstName}</p> <p>Last Name: {data && data.lastName}</p> </Modal.Section> </Modal> </React.Fragment> ); }; ``` ## Drawer example More examples of drawer being used can be seen in [Drawer](/web/ui/drawer). ```jsx live () => { const drawer = useOverlay('title-drawer'); return ( <React.Fragment> <Button onClick={() => drawer.open()} aria-haspopup="dialog"> Toggle Drawer </Button> <Drawer title="Custom Title" model="title-drawer"> <Drawer.Section>Custom Title</Drawer.Section> </Drawer> </React.Fragment> ); }; ``` ## Props The `OverlayProvider` component accepts the following props: | Prop | Type | Default | Description | | ----------------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------- | | `children` | ReactNode | - | The children to render within the overlay provider | | `closeOnPopState` | boolean | `false` | When `true`, any open overlays will automatically close on browser navigation events (like the back button) | ## Handling browser navigation When users navigate through browser history using the back button, you may want open overlays to automatically close. This can be enabled with the `closeOnPopState` prop: ```jsx <OverlayProvider closeOnPopState> <App>{children}</App> </OverlayProvider> ``` This improves user experience by: - Preventing overlays from remaining open after users navigate back - Reducing the need for manual cleanup of overlay state </Tab> --- id: page-body category: Content title: PageBody description: Used to create a page body layout. --- <Tab label="Overview"> ```jsx import { PageBody } from '@uhg-abyss/web/ui/PageBody'; ``` ```jsx live () => { return ( <PageBody> <div>Body Content</div> </PageBody> ); }; ``` ## Full page layout Click below to see an example of a full page that uses the `PageBody` component. ```jsx live <Link href="/fullpagelayout" openNewWindow> Full Page Layout </Link> ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={PageBody} rows={[ { name: 'children', type: 'React Node', description: 'The children element of the body', }, { name: 'fullWidth', type: 'boolean', description: 'Set the max width of the body to full screen', }, { name: 'className', type: 'string', description: 'The class name of PageBody', }, { name: 'ref', type: 'object', description: 'Ref to body root element', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={PageBody} rows={[ { name: 'page-body-root', description: 'Body root', }, { name: 'page-body-container', description: 'Body container', }, ]} /> ``` </Tab> --- id: page-body-intro-v2 category: Content title: V2PageBodyIntro description: Used to create a layout of introductory content at the top of your page body. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=10570-6315 sourceIsTS: true subDirectory: PageBodyIntro/v2 --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="PageBodyIntro" /> ``` ```jsx import { V2PageBodyIntro } from '@uhg-abyss/web/ui/PageBodyIntro'; ``` ## Text Use the `title` prop to supply a title for the V2PageBodyIntro and the `text` prop to supply body copy. A `title` is always required, but the `text` is optional. By default, the title is rendered as an `<h1>` element; this can be customized using the `headingLevel` prop. ```jsx live () => { return ( <V2PageBodyIntro breadcrumbs={[ { title: 'Web', href: '#' }, { title: 'UI', href: '#' }, { title: 'Custom title', href: '#' }, ]} title="Custom title" /> ); }; ``` ## Extra content Extra items can be added below the heading row by passing them as children to the V2PageBodyIntro component. ```jsx live () => { const ThemedText = styled('div', { static: { color: '$page-body-intro-v2.color.text.paragraph', }, dynamic: () => { const typography = useToken('typography')( '$web.semantic.typography.p.md-reg' ); return { typography, }; }, }); return ( <V2PageBodyIntro breadcrumbs={[ { title: 'Web', href: '#' }, { title: 'UI', href: '#' }, { title: 'Extra content', href: '#' }, ]} title="Extra content" text="Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat." > <ThemedText>Extra content 1</ThemedText> <ThemedText>Extra content 2</ThemedText> </V2PageBodyIntro> ); }; ``` ## Variant Use the `variant` prop to change the background color. The possible options are `'neutral'` and `'emphasis'`. The default is `'neutral'`. ```jsx live () => { return ( <Layout.Stack grow> <V2PageBodyIntro variant="neutral" breadcrumbs={[ { title: 'Web', href: '#' }, { title: 'UI', href: '#' }, { title: 'Neutral variant', href: '#' }, ]} title="Neutral variant" text="Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat." /> <V2PageBodyIntro variant="emphasis" breadcrumbs={[ { title: 'Web', href: '#' }, { title: 'UI', href: '#' }, { title: 'Emphasis variant', href: '#' }, ]} title="Emphasis variant" text="Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat." /> </Layout.Stack> ); }; ``` ## Actions Both the navigation and heading rows include slots for actions. The `navAction` prop is typically used for an icon, while the `contentAction` prop is used for a button. We recommend using our [V2Button](/web/ui/button-v2) component for these props. ```jsx live () => { return ( <V2PageBodyIntro breadcrumbs={[ { title: 'Web', href: '#' }, { title: 'UI', href: '#' }, { title: 'Actions example', href: '#' }, ]} title="Actions example" text="Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat." navAction={ <V2Button size="$sm" icon={{ icon: 'print', variant: 'outlined', position: 'icon-only' }} variant="text" onClick={() => { console.log('Clicked nav action'); }} > Print page </V2Button> } contentAction={ <V2Button variant="outline" onClick={() => { console.log('Clicked content action'); }} > Action </V2Button> } /> ); }; ``` ## Sticky positioning Use the `sticky` prop to make the V2PageBodyIntro sticky. If `sticky` is provided with no value, the following styling will be applied to the root element: ```tsx { top: 0, zIndex: 200, position: 'sticky', } ``` To customize the sticky styling, an object containing CSS properties can instead be provided to the `sticky` prop. in the example below, the `top` property is set to match the height of this site's global navbar. ```jsx live () => { const Body = styled('div', { display: 'flex', justifyContent: 'center', paddingTop: '32px', paddingRight: '24px', paddingBottom: '32px', paddingLeft: '24px', backgroundColor: '$white', }); const BodyText = styled('div', { static: { color: '$web.semantic.color.text.content.tertiary', maxWidth: '717px', }, dynamic: () => { const typography = useToken('typography')( '$web.semantic.typography.p.md-reg' ); return { typography, }; }, }); return ( <React.Fragment> <V2PageBodyIntro breadcrumbs={[ { title: 'Web', href: '#' }, { title: 'UI', href: '#' }, { title: 'Sticky positioning', href: '#' }, ]} title="Sticky positioning" text="Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat." sticky={{ top: 'var(--ifm-navbar-height)' }} /> <Body> <BodyText> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum purus risus, efficitur id risus vel, ullamcorper condimentum mi. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec pretium odio risus, ac eleifend lectus porttitor vitae. Suspendisse ex leo, facilisis vitae purus nec, volutpat pharetra arcu. Fusce sodales est tortor, ut ullamcorper neque lobortis in. Nulla facilisi. Aenean non egestas nisl, eu fermentum lorem. Maecenas bibendum ligula id leo iaculis viverra. Nulla tristique nulla tellus, et pharetra massa pulvinar nec. Vivamus in mi in mi scelerisque varius eu tempor tellus. Nam sit amet placerat ante, ac maximus erat. Nullam suscipit mollis metus, imperdiet imperdiet ipsum auctor a. Suspendisse aliquam, erat at mollis tempus, ex sapien fringilla elit, nec blandit elit nibh vel velit. In rhoncus lorem et laoreet bibendum. <br /> <br /> Integer nec quam vitae augue consectetur ultricies. Aliquam vitae viverra dui, vel aliquet purus. Donec ut blandit nisi. Aliquam eget urna volutpat, accumsan turpis ut, laoreet mi. Pellentesque nulla elit, sodales congue tincidunt et, rhoncus eget diam. Cras dapibus at diam ac auctor. Integer faucibus et ligula eleifend ornare. Cras id quam ut enim condimentum pretium et id ex. Nam ut leo non arcu elementum scelerisque sit amet non lectus. Nunc sit amet risus sollicitudin, auctor nulla ac, mollis velit. Donec scelerisque molestie erat at lacinia. Nam viverra convallis libero vitae fermentum. <br /> <br /> Sed consequat felis eget nisl porta, vitae faucibus arcu aliquam. Sed ac nulla nec lectus tempor luctus id a velit. Integer nec rutrum mi. Ut pulvinar quis sem sed porta. Vivamus ut felis sit amet tellus accumsan rhoncus. Sed a scelerisque ante, et faucibus ligula. Praesent ligula nulla, iaculis at maximus a, posuere in odio. </BodyText> </Body> </React.Fragment> ); }; ``` ## Hide bottom border Use the `hideBottomBorder` prop to remove the bottom border of the V2PageBodyIntro. The default value is `false`. ```jsx live () => { return ( <V2PageBodyIntro breadcrumbs={[ { title: 'Web', href: '#' }, { title: 'UI', href: '#' }, { title: 'Hide bottom border', href: '#' }, ]} title="Hide bottom border" text="Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat." hideBottomBorder /> ); }; ``` ## Responsiveness On screens less than 744px wide, the V2PageBodyIntro will adjust its layout. Resize the window to see the change! ```jsx live () => { const ThemedText = styled('div', { static: { color: '$page-body-intro-v2.color.text.paragraph', }, dynamic: () => { const typography = useToken('typography')( '$web.semantic.typography.p.md-reg' ); return { typography, }; }, }); return ( <V2PageBodyIntro breadcrumbs={[ { title: 'Web', href: '#' }, { title: 'UI', href: '#' }, { title: 'Responsiveness', href: '#' }, ]} title="Responsiveness" text="Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat." navAction={ <V2Button size="$sm" icon={{ icon: 'print', variant: 'outlined', position: 'icon-only' }} variant="text" onClick={() => { console.log('Clicked nav action'); }} > Print page </V2Button> } contentAction={ <V2Button variant="outline" onClick={() => { console.log('Clicked content action'); }} > Action </V2Button> } > <ThemedText>Extra content</ThemedText> </V2PageBodyIntro> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2PageBodyIntro" propTypeName="PageBodyIntroProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2ClassesTable title="V2PageBodyIntro" classes={[V2PageBodyIntroClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> <h2>Known issue</h2> V2PageBodyIntro is a page templating component. In its current state, it does not define the page's main content section, which is important for screen readers and other assistive technologies. To ensure that the main content is properly defined, you should wrap the V2PageBodyIntro along with the rest of the page content in an HTML `<main>` element with `id="main-content"`. Note that doing so may result in accessibility errors from tooling such as Evinced stating that the breadcrumbs should not be placed within the main content. This will be addressed in a future Abyss update when we revisit page template components. <h2>Example</h2> ```jsx live () => { const Body = styled('div', { static: { display: 'flex', justifyContent: 'center', paddingTop: '32px', paddingRight: '24px', paddingBottom: '32px', paddingLeft: '24px', backgroundColor: '$white', color: '$web.semantic.color.text.content.tertiary', }, dynamic: () => { const typography = useToken('typography')( '$web.semantic.typography.p.md-reg' ); return { typography, }; }, }); const BodyWrapper = styled('div', { maxWidth: '1088px', }); const StyledHeading = styled(Heading, { marginBottom: '16px', }); const BodyText = styled('p', { marginBottom: '16px', }); return ( <React.Fragment> <V2PageBodyIntro sticky={{ top: 'var(--ifm-navbar-height)' }} breadcrumbs={[ { title: 'Web', href: '#' }, { title: 'UI', href: '#' }, { title: 'V2PageBodyIntro', href: '#' }, { title: 'Page structure', href: '#' }, ]} title="Page structure" text="The structure of a page is critical for communicating its content and meaning." navAction={ <V2Button size="$sm" icon={{ icon: 'print', variant: 'outlined', position: 'icon-only' }} variant="outline" onClick={() => { console.log('Clicked nav action'); }} > Print page </V2Button> } contentAction={ <V2Button variant="outline" onClick={() => { console.log('Clicked content action'); }} > Approve </V2Button> } /> <Body> <BodyWrapper> <Heading.Level> <StyledHeading>Typical content layout and structure</StyledHeading> <Heading.Level> <StyledHeading>Page header</StyledHeading> <BodyText> The topmost part of the page typically starts with the site logo and main navigation. </BodyText> <Heading.Level> <StyledHeading>Main navigation / menu</StyledHeading> <BodyText> The main navigation typically contains links or menus for the main topic or functional areas of the site. Site search is also a common feature. Main nav should be consistently presented on all pages to provide a predictable frame of references for visitors. </BodyText> <StyledHeading>Breadcrumb navigation</StyledHeading> <BodyText> On most content pages, the addition of{' '} <V2Link href="https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/"> breadcrumb navigation </V2Link>{' '} shows the location of the current page relative to home. This helps support users who choose to browse and navigate the site instead of using search. </BodyText> </Heading.Level> <StyledHeading>Main content</StyledHeading> <BodyText> This is the core section of the page containing the information the visitor wants to access. </BodyText> <Heading.Level> <StyledHeading>Primary heading (h1)</StyledHeading> <BodyText> The first thing users, especially screen reader users, expect is a primary heading or heading level 1. It signals the start of the main content and should contain the keywords—if not the exact text—of the link(s) used to access it. Heading text also should be found in the page title. </BodyText> <BodyText> As with a good outline, sub-topics should have visible and programmatic headings. These should be nested appropritely creating a meaningful "table of contents" for the page content—especially if it is lengthy and covers many subjects. </BodyText> <StyledHeading>Body copy</StyledHeading> <BodyText> The first thing users, especially screen reader users, expect is a primary heading or heading level 1. It signals the start of the main content and should contain the keywords—if not the exact text—of the link(s) used to access it. Heading text also should be found in the page title. </BodyText> </Heading.Level> <StyledHeading>Page footer</StyledHeading> <BodyText> The bottom part of the page is the footer. It typically contains common but lower priority information visitors may want. Here is where copyright and legal notices, support features, and other details are placed. Like the page header, it should be a common, unchanging reference point on all pages. </BodyText> </Heading.Level> </Heading.Level> </BodyWrapper> </Body> </React.Fragment> ); }; ``` </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={V2PageBodyIntro} keys={['pageBodyIntroV2']} /> ``` </Tab> --- id: page-body-intro category: Content title: PageBodyIntro description: Used to create a layout of introductory content at the top of your page body. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=13068-50542 subDirectory: PageBodyIntro/v1 --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="PageBodyIntro"></Docs.V2MigrationBanner> ``` ```jsx import { PageBodyIntro } from '@uhg-abyss/web/ui/PageBodyIntro'; ``` ## PageBodyIntro Use `PageBodyIntro` to wrap all the corresponding sub-components and construct an introductory collection of content for your page body. To increase or decrease the default spacing for the individual rows use the `rowSpace` prop. To apply sticky positioning to `PageBodyIntro` please use the `sticky` prop and see the [Sticky](#sticky) section below for details on implementation. ```jsx live () => { const subNavLinks = [ { label: 'Home', href: '/web/ui/page-body-intro' }, { label: 'Jump Link 1', href: '#pagebodyintrolinks' }, { label: 'Jump Link 2', href: '#pagebodyintrorequiredkey' }, { label: 'External Link', href: 'https://www.google.com' }, ]; const profileDataListOne = [ { label: 'MPIN', value: '1234457' }, { label: 'NPI', value: '28737823' }, { label: 'TIN', value: '827382847' }, { label: 'Primary Specialty', value: 'Internal Medicine' }, { label: 'Demographic/Contract Status', value: 'Active' }, { label: 'Provider Hold', value: 'No' }, ]; const profileDataListTwo = [ { label: 'Gender', value: 'Male' }, { label: 'Date of Birth', value: '07-12-1973' }, { label: 'Social Security Number', value: '83498484' }, { label: 'Primary Specialty', value: 'Internal Medicine' }, { label: 'Degree', value: 'Medical Doctor' }, ]; const dataSectionContent = ( <Layout.Stack alignItems="left"> <PageBodyIntro.ProfileData profileData={profileDataListOne} /> <PageBodyIntro.ProfileData profileData={profileDataListTwo} /> </Layout.Stack> ); const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, }, { title: 'Open New Tab', onClick: () => { console.log('Open New Tab!'); }, }, { title: 'Save As...', onClick: () => { console.log('Save As...'); }, icon: <IconSymbol icon="save" />, }, ]; return ( <PageBodyIntro> <PageBodyIntro.Row> <Breadcrumbs size={14} divider="/" items={[ { title: 'Home', href: '/' }, { title: 'Getting Started', href: '/web/developers/overview/', }, { title: 'Breadcrumbs', href: '/web/ui/breadcrumbs/' }, ]} /> <DropdownMenu label="Table Actions" hideLabel after={<IconSymbol icon="more_vert" />} menuItems={menuItems} /> </PageBodyIntro.Row> <PageBodyIntro.Row> <PageBodyIntro.Title>Page Title</PageBodyIntro.Title> <DropdownMenu label="Options" before={<IconSymbol icon="grid_view" />} after={<IconSymbol icon="keyboard_arrow_down" />} menuItems={menuItems} /> </PageBodyIntro.Row> <PageBodyIntro.Row> <PageBodyIntro.Profile headingSection={ <PageBodyIntro.ProfileHeading> Profile Name </PageBodyIntro.ProfileHeading> } dataSection={dataSectionContent} statusSection={<Badge variant="success">Verified</Badge>} /> </PageBodyIntro.Row> <PageBodyIntro.Row> <PageBodyIntro.Links linkData={subNavLinks} /> <PageBodyIntro.RequiredKey /> </PageBodyIntro.Row> </PageBodyIntro> ); }; ``` ### Sticky Use the `sticky` prop to assign a sticky position to the `PageBodyIntro` root element. To enable the default settings simply add the `sticky` prop to `PageBodyIntro` and the following css properties will be applied: ```jsx { position: 'sticky', boxShadow: 'rgb(0 0 0 / 10%) 0px 1px 2px 0px', top: 0, zIndex: 200, } ``` You can override any of these properties and/or include new css properties by passing them in as an object to the `sticky` prop. For example `sticky={{ top: 55 }}`. ```jsx live () => { const subNavLinks = [ { label: 'Jump Link 1', href: '#pagebodyintroprofile' }, { label: 'Jump Link 2', href: '#pagebodyintrolinks' }, { label: 'Jump Link 3', href: '#pagebodyintrorequiredkey' }, { label: 'External Link', href: 'https://www.google.com' }, ]; const profileDataListOne = [ { label: 'MPIN', value: '1234457' }, { label: 'NPI', value: '28737823' }, { label: 'TIN', value: '827382847' }, { label: 'Primary Specialty', value: 'Internal Medicine' }, { label: 'Demographic/Contract Status', value: 'Active' }, { label: 'Provider Hold', value: 'No' }, ]; const profileDataListTwo = [ { label: 'Gender', value: 'Male' }, { label: 'Date of Birth', value: '07-12-1973' }, { label: 'Social Security Number', value: '83498484' }, { label: 'Primary Specialty', value: 'Internal Medicine' }, { label: 'Degree', value: 'Medical Doctor' }, ]; const dataSectionContent = ( <Layout.Stack alignItems="left"> <PageBodyIntro.ProfileData profileData={profileDataListOne} /> <PageBodyIntro.ProfileData profileData={profileDataListTwo} /> </Layout.Stack> ); const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, }, { title: 'Open New Tab', onClick: () => { console.log('Open New Tab!'); }, }, { title: 'Save As...', onClick: () => { console.log('Save As...'); }, icon: <IconSymbol icon="save" />, }, ]; const form = useForm({}); const onSubmit = (data) => { console.log('data', data); }; const options = [ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]; return ( <PageBody> <PageBodyIntro sticky={{ top: 55, }} > <PageBodyIntro.Row> <Breadcrumbs size={14} divider="/" items={[ { title: 'Home', href: '/' }, { title: 'Getting Started', href: '/web/developers/overview/', }, { title: 'Breadcrumbs', href: '/web/ui/breadcrumbs/' }, ]} /> <DropdownMenu label="Table Actions" hideLabel after={<IconSymbol icon="more_vert" />} menuItems={menuItems} /> </PageBodyIntro.Row> <PageBodyIntro.Row> <PageBodyIntro.Title>Page Title</PageBodyIntro.Title> <DropdownMenu label="Options" before={<IconSymbol icon="grid_view" />} after={<IconSymbol icon="keyboard_arrow_down" />} menuItems={menuItems} /> </PageBodyIntro.Row> <PageBodyIntro.Row> <PageBodyIntro.Profile headingSection={ <PageBodyIntro.ProfileHeading> Profile Name </PageBodyIntro.ProfileHeading> } dataSection={dataSectionContent} statusSection={<Badge variant="success">Verified</Badge>} /> </PageBodyIntro.Row> <PageBodyIntro.Row> <PageBodyIntro.Links linkData={subNavLinks} /> <PageBodyIntro.RequiredKey /> </PageBodyIntro.Row> </PageBodyIntro> <div style={{ padding: '48px 24px', backgroundColor: 'white', }} > <Layout.Stack alignItems="left" grow> <Heading offset={2}>Fill Out Form</Heading> <FormProvider state={form} onSubmit={onSubmit} highlighted> <SelectInput label="Select List Usage" model="selectlist" placeholder="Select List Form Provider" options={options} validators={{ required: true }} /> <SelectInputMulti label="Your favorite framework/library" placeholder="Pick one" model="frameworks" isSearchable options={options} validators={{ required: true }} /> <DateInput model="test-date" validators={{ required: true }} /> <TextInput label="TextInput Form" placeholder="Form" model="textForm" isClearable validators={{ required: true }} /> <Button type="submit" style={{ marginTop: '15px' }}> Submit </Button> </FormProvider> </Layout.Stack> </div> </PageBody> ); }; ``` ## PageBodyIntro.Row Use `PageBodyIntro.Row` to create a new row. Use the `alignLayout` prop to change the left-to-right layout and `alignItems` to adjust the top-to-bottom alignment. The default `alignLayout` setting is `spaced` and `alignItems` defaults to `center`. ```jsx live () => { const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, }, { title: 'Open New Tab', onClick: () => { console.log('Open New Tab!'); }, }, { title: 'Save As...', onClick: () => { console.log('Save As...'); }, icon: <IconSymbol icon="save" />, }, ]; return ( <PageBodyIntro> <PageBodyIntro.Row> <Breadcrumbs size={14} divider="/" items={[ { title: 'Home', href: '/' }, { title: 'Getting Started', href: '/web/developers/overview/', }, { title: 'Breadcrumbs', href: '/web/ui/breadcrumbs/' }, ]} /> <DropdownMenu label="Table Actions" hideLabel after={<IconSymbol icon="more_vert" />} menuItems={menuItems} /> </PageBodyIntro.Row> </PageBodyIntro> ); }; ``` ## PageBodyIntro.Title Use `PageBodyIntro.Title` for the page title text. If you need to change the heading-level pass the desired heading-level string to the `headingLevel` prop. The default setting is `h2`. ```jsx live () => { return ( <PageBodyIntro> <PageBodyIntro.Row> <PageBodyIntro.Title>Page Title</PageBodyIntro.Title> </PageBodyIntro.Row> </PageBodyIntro> ); }; ``` ## PageBodyIntro.Profile `PageBodyIntro.Profile` is used to hold all content related to profile information and maintain the recommended layout for this section. It is comprised of three primary sections and includes a prop to supply the content for each, `headingSection`, `dataSection` and `statusSection`. ```jsx live () => { const profileData = [ { label: 'MPIN', value: '1234457' }, { label: 'NPI', value: '28737823' }, { label: 'TIN', value: '827382847' }, { label: 'Primary Specialty', value: 'Internal Medicine' }, { label: 'Demographic/Contract Status', value: 'Active' }, { label: 'Provider Hold', value: 'No' }, ]; return ( <PageBodyIntro> <PageBodyIntro.Row> <PageBodyIntro.Profile headingSection={ <PageBodyIntro.ProfileHeading> Profile Name </PageBodyIntro.ProfileHeading> } dataSection={<PageBodyIntro.ProfileData profileData={profileData} />} statusSection={<Badge variant="success">Verified</Badge>} /> </PageBodyIntro.Row> </PageBodyIntro> ); }; ``` See the following sub-sections for further detail on the associated sub-components and the implementation of each. ### Profile heading Use `PageBodyIntro.ProfileHeading` for the profile heading text. If you need to change the heading-level pass the desired heading-level string to the `headingLevel` prop. The default setting is `h3`. To insert into the profile section layout pass this component into the `headingSection` prop within `PageBodyIntro.Profile`. ```jsx live () => { return ( <PageBodyIntro> <PageBodyIntro.Row> <PageBodyIntro.Profile headingSection={ <PageBodyIntro.ProfileHeading> Profile Name </PageBodyIntro.ProfileHeading> } /> </PageBodyIntro.Row> </PageBodyIntro> ); }; ``` ### Profile data `PageBodyIntro.ProfileData` is used to provide a list of meta-data associated with the current profile. Use the `profileData` prop to pass in an array of objects that include the following two properties: - `label` : label that will be displayed for the item - `value` : corresponding value that will be displayed for the item To insert into the profile section layout pass this component into the `dataSection` prop within `PageBodyIntro.Profile`. ```jsx live () => { const profileData = [ { label: 'MPIN', value: '1234457' }, { label: 'NPI', value: '28737823' }, { label: 'TIN', value: '827382847' }, { label: 'Primary Specialty', value: 'Internal Medicine' }, { label: 'Demographic/Contract Status', value: 'Active' }, { label: 'Provider Hold', value: 'No' }, ]; return ( <PageBodyIntro> <PageBodyIntro.Row> <PageBodyIntro.Profile dataSection={<PageBodyIntro.ProfileData profileData={profileData} />} /> </PageBodyIntro.Row> </PageBodyIntro> ); }; ``` ### Profile status There is no sub-component to handle this section but rather it is recommended a [Badge](/web/ui/badge) or something similar be utilized and passed into the `statusSection` prop within `PageBodyIntro.Profile`. ```jsx live () => { const profileData = [ { label: 'MPIN', value: '1234457' }, { label: 'NPI', value: '28737823' }, { label: 'TIN', value: '827382847' }, { label: 'Primary Specialty', value: 'Internal Medicine' }, { label: 'Demographic/Contract Status', value: 'Active' }, { label: 'Provider Hold', value: 'No' }, ]; return ( <PageBodyIntro> <PageBodyIntro.Row> <PageBodyIntro.Profile headingSection={ <PageBodyIntro.ProfileHeading> Profile Name </PageBodyIntro.ProfileHeading> } dataSection={<PageBodyIntro.ProfileData profileData={profileData} />} statusSection={<Badge variant="success">Verified</Badge>} /> </PageBodyIntro.Row> </PageBodyIntro> ); }; ``` If the available space below the profile heading is not sufficient and you prefer to have the status located at the bottom of this section simply add it within a new `PageBodyIntro.Row`. In the example below the [StatusIndicator](/web/ui/status-indicator/#width) is being used in full-width. ```jsx live () => { const profileData = [ { label: 'MPIN', value: '1234457' }, { label: 'NPI', value: '28737823' }, { label: 'TIN', value: '827382847' }, { label: 'Primary Specialty', value: 'Internal Medicine' }, { label: 'Demographic/Contract Status', value: 'Active' }, { label: 'Provider Hold', value: 'No' }, ]; return ( <PageBodyIntro> <PageBodyIntro.Row> <PageBodyIntro.Profile headingSection={ <PageBodyIntro.ProfileHeading> Profile Name </PageBodyIntro.ProfileHeading> } dataSection={<PageBodyIntro.ProfileData profileData={profileData} />} /> </PageBodyIntro.Row> <PageBodyIntro.Row alignItems="top"> <StatusIndicator variant="success" statusLabel="Status label" width="100%" > <StatusIndicator.Icon title="success" /> <StatusIndicator.Text>Status</StatusIndicator.Text> <StatusIndicator.Link href="#">Link</StatusIndicator.Link> </StatusIndicator> </PageBodyIntro.Row> </PageBodyIntro> ); }; ``` ## PageBodyIntro.Links Use `PageBodyIntro.Links` to add a row of links. Use the `linkData` prop to pass in an array of objects that include the following three properties: - `label` : label that will be displayed for the item - `href` : sets the url of desired location - `isActive` : By default, the component will automatically detect if the current location path matches the item path and set the active state. To override the built-in path detection, use this prop to directly set the item state to active. When active, the class `abyss-page-body-intro-links-list-item-link-active` will be added to the item element. ```jsx live () => { const linkData = [ { label: 'Jump Link 1', href: '#pagebodyintrorow' }, { label: 'Jump Link 2', href: '#pagebodyintrotitle' }, { label: 'Jump Link 3', href: '#pagebodyintroprofile' }, { label: 'External Link', href: 'https://www.google.com' }, ]; return ( <PageBodyIntro> <PageBodyIntro.Row> <PageBodyIntro.Links linkData={linkData} /> </PageBodyIntro.Row> </PageBodyIntro> ); }; ``` One common alternative to `PageBodyIntro.Links` would be the usage of [ToggleTabs](/web/ui/toggle-tabs) as seen in the following example: ```jsx live () => { const [toggleValue, setToggleValue] = useState('low-d'); return ( <PageBodyIntro> <PageBodyIntro.Row> <ToggleTabs onChange={(e) => setToggleValue(e.target.value)} value={toggleValue} > <ToggleTabs.Tab label="Demographics" value="low-d" /> <ToggleTabs.Tab label="Policy" value="bind" /> <ToggleTabs.Tab label="Care Provider" value="bal" /> <ToggleTabs.Tab label="Coverage" value="low-p" /> <ToggleTabs.Tab label="Benefits" value="full" /> </ToggleTabs> </PageBodyIntro.Row> </PageBodyIntro> ); }; ``` ## PageBodyIntro.RequiredKey Use `PageBodyIntro.RequiredKey` to display a key that corresponds with required fields from an associated form. The default message text is `Required` but a custom message can be utilized by wrapping the text in `PageBodyIntro.RequiredKey`. This component can be utilized outside of `PageBodyIntro` and is only recommended to be placed within `PageBodyIntro` if a sticky position is used and the key will be visible while the user navigates through the associated form located below. Please see the [Sticky](#sticky) section for an example. ```jsx live () => { return ( <PageBodyIntro> <PageBodyIntro.Row> <PageBodyIntro.RequiredKey /> </PageBodyIntro.Row> </PageBodyIntro> ); }; ``` ## Full page layout Click below to see an example of a full page that uses the `PageBodyIntro` component. ```jsx live <Link href="/fullpagelayout" openNewWindow> Full Page Layout </Link> ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={PageBodyIntro} rows={[ { name: 'children', type: 'ReactNode', description: 'The element(s) PageBodyIntro wraps', }, { name: 'rowSpace', type: 'number | string', description: 'Set the spacing between rows within PageBodyIntro', }, { name: 'sticky', type: 'boolean | object', description: 'Apply sticky positioning to PageBodyIntro root element', }, ]} /> ``` ```jsx render <Docs.PropsTable of={PageBodyIntro.Row} rows={[ { name: 'children', type: 'ReactNode', description: 'The element(s) PageBodyIntro.Row wraps', }, { name: 'alignLayout', type: "'spaced' | 'left' | 'center' | 'right'", description: 'Set the left-to-right alignment of items on the main axis', }, { name: 'alignItems', type: "'top' | 'center' | 'bottom'", description: 'Set the top-to-bottom alignment of items on the cross axis', }, ]} /> ``` ```jsx render <Docs.PropsTable of={PageBodyIntro.Title} rows={[ { name: 'children', type: 'string', description: 'The heading text content of PageBodyIntro.Title', }, { name: 'headingLevel', type: "'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'", description: 'Set the heading level', }, ]} /> ``` ```jsx render <Docs.PropsTable of={PageBodyIntro.Profile} rows={[ { name: 'headingSection', type: 'ReactNode', description: 'Set the content for the heading section within PageBodyIntro.Profile', }, { name: 'dataSection', type: 'ReactNode', description: 'Set the content for the data section within PageBodyIntro.Profile', }, { name: 'statusSection', type: 'ReactNode', description: 'Set the content for the status section within PageBodyIntro.Profile', }, ]} /> ``` ```jsx render <Docs.PropsTable of={PageBodyIntro.ProfileHeading} rows={[ { name: 'children', type: 'string', description: 'The heading text content of PageBodyIntro.ProfileHeading', }, { name: 'headingLevel', type: "'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'", description: 'Set the heading level', }, ]} /> ``` ```jsx render <Docs.PropsTable of={PageBodyIntro.ProfileData} rows={[ { name: 'profileData', type: 'array[object]', description: 'Array of objects to be formatted and displayed within PageBodyIntro.ProfileData { label: string, value: string }', }, ]} /> ``` ```jsx render <Docs.PropsTable of={PageBodyIntro.Links} rows={[ { name: 'linkData', type: 'array[object]', description: 'Array of objects to be formatted and displayed as links within PageBodyIntro.Links { label: string, href: string, isActive: boolean }', }, ]} /> ``` ```jsx render <Docs.PropsTable of={PageBodyIntro.RequiredKey} rows={[ { name: 'children', type: 'string', description: 'The text content of PageBodyIntro.RequiredKey', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={PageBodyIntro} rows={[ { name: 'page-body-intro-root', description: 'Page body intro root element', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={PageBodyIntro.Row} rows={[ { name: 'page-body-intro-row-container', description: 'Page body intro row container element', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={PageBodyIntro.Title} rows={[ { name: 'page-body-intro-title-container', description: 'Page body intro title container element', }, { name: 'page-body-intro-title-text', description: 'Page body intro title text element', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={PageBodyIntro.Profile} rows={[ { name: 'page-body-intro-profile-container', description: 'Page body intro profile container element', }, { name: 'page-body-intro-profile-heading-status-container', description: 'Page body intro profile heading and status container element', }, { name: 'page-body-intro-profile-data-container', description: 'Page body intro profile data container element', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={PageBodyIntro.ProfileHeading} rows={[ { name: 'page-body-intro-profile-heading-text', description: 'Page body intro profile-heading text element', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={PageBodyIntro.ProfileData} rows={[ { name: 'page-body-intro-profile-data-list-container', description: 'Page body intro profile-data list container element', }, { name: 'page-body-intro-profile-data-list-item', description: 'Page body intro profile-data list item element', }, { name: 'page-body-intro-profile-data-list-item-label-text', description: 'Page body intro profile-data list item label text element', }, { name: 'page-body-intro-profile-data-list-item-value-text', description: 'Page body intro profile-data list item value text element', }, { name: 'page-body-intro-profile-data-list-item-divider', description: 'Page body intro profile-data list item divider element', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={PageBodyIntro.Links} rows={[ { name: 'page-body-intro-links-list-container', description: 'Page body intro links list container element', }, { name: 'page-body-intro-links-list-item', description: 'Page body intro links list item element', }, { name: 'page-body-intro-links-list-item-link', description: 'Page body intro links list item link element', }, { name: 'page-body-intro-links-list-item-link-active', description: 'Page body intro links list item link element when active', }, { name: 'page-body-intro-links-list-item-divider', description: 'Page body intro links list item divider element', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={PageBodyIntro.RequiredKey} rows={[ { name: 'page-body-intro-required-key-container', description: 'Page body intro required key container element', }, { name: 'page-body-intro-required-key-color-box', description: 'Page body intro required key color box element', }, { name: 'page-body-intro-required-key-text-asterisk-container', description: 'Page body intro required key text and asterisk container element', }, { name: 'page-body-intro-required-key-text', description: 'Page body intro required key text element', }, { name: 'page-body-intro-required-key-asterisk', description: 'Page body intro required key asterisk element', }, ]} /> ``` </Tab> --- id: page-footer category: Content title: PageFooter description: Used to create a page footer. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=0-1209 subDirectory: PageFooter/v1 --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="PageFooter"></Docs.V2MigrationBanner> ``` ```jsx import { PageFooter } from '@uhg-abyss/web/ui/PageFooter'; ``` ```jsx live () => { const subFooterLinks = [ { label: 'Privacy', href: 'https://www.google.com' }, { label: 'Terms Of Use', href: '#' }, { label: 'Opt Out', href: '#' }, { label: 'Accessibility', href: '#' }, ]; return ( <PageFooter subFooterLinks={subFooterLinks} subFooterTitle="United HealthCare Services, Inc" subFooterBottomText="Last updated: 03/15/2023 at 12:01 AM CT" > <PageFooter.Section title="Section Title"> <PageFooter.Link href="#">Page Link</PageFooter.Link> <PageFooter.Link href="#">Page Link</PageFooter.Link> <PageFooter.Link href="#">Page Link</PageFooter.Link> <PageFooter.Link href="#">Page Link</PageFooter.Link> </PageFooter.Section> <PageFooter.Section title="Section Title"> <PageFooter.Link href="#">Page Link</PageFooter.Link> <PageFooter.Link href="#">Page Link</PageFooter.Link> <PageFooter.Link href="#">Page Link</PageFooter.Link> <PageFooter.Link href="#">Page Link</PageFooter.Link> </PageFooter.Section> <PageFooter.Section title="Section Title"> <PageFooter.Link href="#">Page Link</PageFooter.Link> <PageFooter.Link href="#">Page Link</PageFooter.Link> <PageFooter.Link href="#">Page Link</PageFooter.Link> <PageFooter.Link href="#">Page Link</PageFooter.Link> </PageFooter.Section> <PageFooter.Section title="Section Title"> <PageFooter.Link href="#">Page Link</PageFooter.Link> <PageFooter.Link href="#">Page Link</PageFooter.Link> <PageFooter.Link href="#">Page Link</PageFooter.Link> <PageFooter.Link href="#">Page Link</PageFooter.Link> </PageFooter.Section> </PageFooter> ); }; ``` ## Sub footer title Use the `subFooterTitle` prop to change the title of the copyright section. ```jsx live <PageFooter subFooterTitle="United HealthCare Services, Inc" /> ``` ## Sub footer bottom text Use the `subFooterBottomText` prop to add content below the copyright text. ```jsx live <PageFooter subFooterTitle="United HealthCare Services, Inc" subFooterBottomText="Last updated: 03/15/2023 at 12:01 AM CT" /> ``` ## Sub footer links Use the `subFooterLinks` prop to add the sub-footer link array. Use `href` to set the link to a different page, and use `label` to set the descriptive text for the `href`. ```jsx live () => { const subFooterLinks = [ { label: 'Privacy', href: '#' }, { label: 'Terms Of Use', href: '#' }, { label: 'Opt Out', href: '#' }, { label: 'Accessibility', href: '#' }, ]; return <PageFooter subFooterLinks={subFooterLinks} />; }; ``` ## Footer.Section ### Title Use the `title` prop to add a title to the footer section container. For accessibility purposes, section titles are implemented as HTML headers—`<h2>` elements by default. Use the `headingLevel` prop to change the heading level. ```jsx live <PageFooter> <PageFooter.Section title="h2 Section Title" /> <PageFooter.Section title="h3 Section Title" headingLevel={3} /> </PageFooter> ``` ### Spread sections Use the `spreadSections` prop to spread section column content across the footer container. This is only recommended when using 4 or more section columns. Default is set to `false` and content is left-aligned. ```jsx live () => { const subFooterLinks = [ { label: 'Privacy', href: '#' }, { label: 'Terms Of Use', href: '#' }, { label: 'Opt Out', href: '#' }, { label: 'Accessibility', href: '#' }, ]; return ( <PageFooter subFooterLinks={subFooterLinks} subFooterTitle="United HealthCare Services, Inc" spreadSections > <PageFooter.Section title="Section Title"> <PageFooter.Link href="#">Page Link</PageFooter.Link> <PageFooter.Link href="#">Page Link</PageFooter.Link> <PageFooter.Link href="#">Page Link</PageFooter.Link> <PageFooter.Link href="#">Page Link</PageFooter.Link> </PageFooter.Section> <PageFooter.Section title="Section Title"> <PageFooter.Link href="#">Page Link</PageFooter.Link> <PageFooter.Link href="#">Page Link</PageFooter.Link> <PageFooter.Link href="#">Page Link</PageFooter.Link> <PageFooter.Link href="#">Page Link</PageFooter.Link> </PageFooter.Section> <PageFooter.Section title="Section Title"> <PageFooter.Link href="#">Page Link</PageFooter.Link> <PageFooter.Link href="#">Page Link</PageFooter.Link> <PageFooter.Link href="#">Page Link</PageFooter.Link> <PageFooter.Link href="#">Page Link</PageFooter.Link> </PageFooter.Section> <PageFooter.Section title="Section Title"> <PageFooter.Link href="#">Page Link</PageFooter.Link> <PageFooter.Link href="#">Page Link</PageFooter.Link> <PageFooter.Link href="#">Page Link</PageFooter.Link> <PageFooter.Link href="#">Page Link</PageFooter.Link> </PageFooter.Section> </PageFooter> ); }; ``` ## Footer.Link The Footer Link leverages props from the Link component. Find additional resources on our [Link](/web/ui/link) page. ### Href Use the `href` prop to set the URL of the link. ```jsx live <PageFooter> <PageFooter.Section title="Section Title"> <PageFooter.Link href="https://www.google.com"> Regular Link </PageFooter.Link> <PageFooter.Link href="#">Based On Root Path</PageFooter.Link> </PageFooter.Section> </PageFooter> ``` ### onClick Use the `onClick` prop to trigger a custom function when the footer link title is clicked. ```jsx live <PageFooter> <PageFooter.Section title="Section Title"> <PageFooter.Link onClick={() => { console.log('onClick triggered'); }} > Page LinkonClick </PageFooter.Link> </PageFooter.Section> </PageFooter> ``` ### Open in new window Use the `openNewWindow` prop to specify whether links open in a new window. `openNewWindow` is false for relative links. Absolute links will open in a new window. ```jsx live <PageFooter> <PageFooter.Section title="Relative Link"> <PageFooter.Link href="#">Relative - Same Window</PageFooter.Link> <PageFooter.Link href="#" openNewWindow> Relative - New Window </PageFooter.Link> </PageFooter.Section> <PageFooter.Section title="Absolute Link"> <PageFooter.Link href="https://www.google.com" openNewWindow={false}> Absolute - Same Window </PageFooter.Link> <PageFooter.Link href="https://www.google.com"> Absolute - New Window </PageFooter.Link> </PageFooter.Section> </PageFooter> ``` ## Footer name and sub footer name `footerName` and `subFooterName` are used for accessibility purposes. If you have more than one footer, `footerName` and `subFooterName` can help differentiate them for screen readers. ```jsx live <Layout.Stack grow> <PageFooter footerName="footer 1" subFooterName="sub footer 1" subFooterTitle="first footer" /> <PageFooter footerName="footer 2" subFooterName="sub footer 2" subFooterTitle="second footer" /> </Layout.Stack> ``` ## Full page layout Click below to see an example of a full page that uses the `PageFooter` component. ```jsx live <Link href="/fullpagelayout" openNewWindow> Full Page Layout </Link> ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={PageFooter} rows={[ { name: 'children', type: 'React Node', description: 'The children element of the footer', }, { name: 'subFooterTitle', type: 'string', description: 'Sets the title of the sub-footer copyright section', }, { name: 'subFooterBottomText', type: 'string | node', description: 'Sets the text of the sub-footer below the copyright section', }, { name: 'subFooterLinks', type: 'array[object]', description: 'Array of sub-footer data. { label: string, href: string}', }, { name: 'fullWidth', type: 'boolean', description: 'Set the max width of the footer to full screen', }, { name: 'spreadSections', type: 'boolean', description: 'Spread section column content across the footer container', }, { name: 'footerName', type: 'string', description: 'aria-label for footer', }, { name: 'subFooterName', type: 'string', description: 'aria label for sub footer', default: 'sub footer', }, { name: 'brandmark', type: 'React Node', description: 'The brandmark of PageFooter component', }, { name: 'bottomFixed', type: 'boolean', description: 'It sets the bottom width of the PageFooter', }, { name: 'footerRootTag', type: 'string', description: 'Allows for setting an alternative element tag for the root element when using PageFooter within an existing footer structure', default: 'footer', }, { name: 'footerLinksTag', type: 'string', description: 'Allows for setting an alternative element tag for the links element when using PageFooter within an existing footer structure', }, { name: 'ref', type: 'object', description: 'Ref to footer root element', }, ]} /> ``` ```jsx render <Docs.PropsTable of={PageFooter.Section} rows={[ { name: 'children', type: 'React Node', description: 'The children element of the footer section', }, { name: 'title', type: 'string', description: 'Set the title of the footer section container', }, { name: 'headingLevel', type: '1 | 2 | 3 | 4 | 5 | 6', description: 'The semantic heading level to use for the footer section title', default: '2', }, ]} /> ``` ```jsx render <Docs.PropsTable of={PageFooter.Link} rows={[ { name: 'href', type: 'string', description: 'Set the URL of the link', }, { name: 'children', type: 'ReactNode', description: 'Set the text of the link', }, { name: 'onClick', type: 'function', description: 'Used to trigger a custom function when the link is clicked', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={PageFooter} rows={[ { name: 'page-footer-root', description: 'Footer root', }, { name: 'page-footer-container', description: 'Footer container', }, { name: 'page-footer-links', description: 'Footer links section', }, { name: 'page-footer-brandmark-wrapper', description: 'Brandmark wrapper', }, { name: 'page-footer-brandmark-container', description: 'Brandmark container', }, { name: 'page-footer-copyright-container', description: 'Sub footer copyright container', }, { name: 'page-footer-copyright', description: 'Sub footer copyright text', }, { name: 'page-footer-bottom-text', description: 'Sub footer text below copyright', }, { name: 'page-footer-sub-wrapper', description: 'Sub footer wrapper', }, { name: 'page-footer-sub-nav', description: 'Sub footer navigation container', }, { name: 'page-footer-sub-list-container', description: 'Sub footer link list container', }, { name: 'page-footer-sub-list', description: 'Sub footer link list', }, { name: 'page-footer-sub-link', description: 'Sub footer link', }, { name: 'page-footer-sub-divider', description: 'Sub footer link divider', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={PageFooter.Section} rows={[ { name: 'page-footer-section', description: 'Footer section element', }, { name: 'page-footer-section-title', description: 'Footer section title', }, { name: 'page-footer-list-container', description: 'Footer list section', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={PageFooter.Link} rows={[ { name: 'page-footer-link-item', description: 'Link item container', }, { name: 'page-footer-link', description: 'Link item', }, { name: 'page-footer-link-icon-insert', description: 'Link item chevron icon insert', }, { name: 'page-footer-link-icon', description: 'Link chevron icon', }, ]} /> ``` </Tab> <Tab label="Accessibility"> ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Tab', description: 'Moves focus to the next focusable element; all focusable elements in the footer are included in the page Tab sequence.', }, { name: 'Shift + Tab', description: 'Moves focus to the previous focusable element; all focusable elements in the footer are included in the page Tab sequence.', }, { name: 'Enter', description: 'When focus is on the link element, pressing Enter will take the user to a separate page.', }, ]} /> ``` ```jsx live () => { const subFooterLinks = [ { label: 'Contact us', href: '#' }, { label: 'Careers', href: '#' }, { label: 'About us', href: '#' }, { label: 'Accessibility', href: '#' }, { label: 'Privacy', href: '#' }, { label: 'Terms Of Use', href: '#' }, { label: 'Legal', href: '#' }, ]; return ( <PageFooter footerName="Primary" subFooterName="Site info" subFooterLinks={subFooterLinks} subFooterTitle="United HealthCare Services, Inc. All rights reserved." subFooterBottomText="Last updated: 09/23/2024 at 8:00 PM CT" brandmark={ <Brandmark brand="uhc" affiliate="uhc" size="$md" variant="stacked_wordmark" color="white" /> } > <PageFooter.Section title="UHC Health Matters"> <PageFooter.Link href="#">Newsroom</PageFooter.Link> <PageFooter.Link href="#">Community</PageFooter.Link> <PageFooter.Link href="#">Medicare articles</PageFooter.Link> <PageFooter.Link href="#">All news & articles</PageFooter.Link> </PageFooter.Section> <PageFooter.Section title="Health & wellness"> <PageFooter.Link href="#">Vaccines</PageFooter.Link> <PageFooter.Link href="#">Flu short</PageFooter.Link> <PageFooter.Link href="#">Page Link</PageFooter.Link> <PageFooter.Link href="#">All health & wellness topics</PageFooter.Link> </PageFooter.Section> <PageFooter.Section title="More UHC sites"> <PageFooter.Link href="#">Employers</PageFooter.Link> <PageFooter.Link href="#">Agents & brokers</PageFooter.Link> <PageFooter.Link href="#">Providers</PageFooter.Link> </PageFooter.Section> </PageFooter> ); }; ``` </Tab> --- id: page-header category: Content title: PageHeader description: Used to create a page header. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=6132-24108 subDirectory: PageHeader/v1 --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="PageHeaderPrimitives"></Docs.V2MigrationBanner> ``` ```jsx import { PageHeaderPrimitives } from '@uhg-abyss/web/ui/PageHeader'; ``` ## Brandmark Use the `Brandmark` subcomponent of `PageHeaderPrimitives` to customize brand mark in page header. Below are the props for Brandmark subcomponent. `logo` - prop to provide the logo that will be displayed on the far left side of the header. By default, it will show either the UHC or Optum logo, depending on the page theme. `logoTitle` - prop to specify additional detail about the title of the page. It will be displayed directly to the right of the main logo, with a vertical divider between the logo and the logo title. `logoRedirect` - prop to provide a link that the `logo` will redirect to when clicked. In most cases, you would want this logo to redirect to your website's home page. If a value is not passed in, the logo will not redirect to anything. ```jsx live <PageHeaderPrimitives.Container css={{ 'abyss-page-header-root': { zIndex: 100, }, }} > <PageHeaderPrimitives.Brandmark logoTitle="Logo Title" /> </PageHeaderPrimitives.Container> ``` ## Hamburger menu Use the `HamburgerMenu` subcomponent of `PageHeaderPrimitives` to show content in a drawer. ```jsx live () => { const [isOpen, setIsOpen] = useState(false); return ( <PageHeaderPrimitives.Container css={{ 'abyss-page-header-root': { zIndex: 100, }, }} > <Layout.Group> <PageHeaderPrimitives.HamburgerMenu onClick={() => { setIsOpen(true); }} type="button" aria-label="Menu" aria-haspopup="dialog" > <IconSymbol icon="menu" color="$primary1" />{' '} </PageHeaderPrimitives.HamburgerMenu> <PageHeaderPrimitives.Brandmark logoTitle="Logo Title" /> </Layout.Group> <Drawer isOpen={isOpen} onClose={() => setIsOpen(false)} title="Menu" position="left" > <Drawer.Section> <Layout.Stack grow space={20} as="ul" css={{ '&[li]': { listStyle: 'none', margin: 0, padding: 0, }, }} > <li> <Text color="$primary1" fontWeight="$bold"> Sample Drawer Content </Text> </li> <li> <Link fontWeight="bold" href="https://abyss.uhc.com/"> Docs Link </Link> </li> <li> Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam. </li> </Layout.Stack> </Drawer.Section> </Drawer> </PageHeaderPrimitives.Container> ); }; ``` ```jsx live () => { const [isOpen, setIsOpen] = useState(false); return ( <PageHeaderPrimitives.Container css={{ 'abyss-page-header-root': { zIndex: 100, }, }} > <PageHeaderPrimitives.Brandmark logoTitle="Logo Title" /> <PageHeaderPrimitives.HamburgerMenu onClick={() => { setIsOpen(true); }} type="button" aria-label="Menu" aria-haspopup="dialog" > <IconSymbol icon="menu" color="$primary1" />{' '} </PageHeaderPrimitives.HamburgerMenu> <Drawer isOpen={isOpen} onClose={() => setIsOpen(false)} title="Menu"> <Drawer.Section> <Layout.Stack grow space={20} as="ul" css={{ '&[li]': { listStyle: 'none', margin: 0, padding: 0, }, }} > <li> <Text color="$primary1" fontWeight="$bold"> Sample Drawer Content </Text> </li> <li> <Link fontWeight="bold" href="https://abyss.uhc.com/"> Docs Link </Link> </li> <li> Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam. </li> </Layout.Stack> </Drawer.Section> </Drawer> </PageHeaderPrimitives.Container> ); }; ``` ## StateRouter Use the `StateRouter` component for deep nesting the routes inside the Drawer component to show content based on route selected. `StateRouter` acts as a provider for nesting through the routes and also gives ability to traverse the path in reverse direction. `Drawer` should be wrapped inside `StateRouter.Provider` while using with `StateRouter`. ```jsx live () => { const [isOpen, setIsOpen] = useState(false); const HomeContent = () => { return ( <React.Fragment> <ul> <li> <PageHeaderPrimitives.DrawerLink title="Utility Dropdown" path="/home/utility" /> </li> <li> <PageHeaderPrimitives.DrawerLink title="Utility Link" href="https://abyss.uhc.com/" /> </li> <li> <PageHeaderPrimitives.DrawerLink title="Sample Dropdown" path="/home/sampleContent" /> </li> </ul> </React.Fragment> ); }; const UtilityContent = () => { return ( <React.Fragment> <Heading css={{ padding: '0px $md' }} offset={4} fontWeight="$bold" id="utility-items-title" > Utility Items </Heading> <Layout.Stack grow as="ul" aria-labelledby="utility-items-title" css={{ '&[li]': { listStyle: 'none', margin: 0, padding: 0, }, }} > <li> <NavMenuPrimitives.MenuItem title="Test Link" description="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vitae lorem posuere augue volutpat tincidunt ut in odio. Sed non vehicula tellus." href="https://abyss.uhc.com/" /> </li> <li> <NavMenuPrimitives.MenuItem title="Test Link 2" description="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vitae lorem posuere augue volutpat tincidunt ut in odio. Sed non vehicula tellus." href="https://abyss.uhc.com/" /> </li> <li> <PageHeaderPrimitives.DrawerLink title="Utility Plans" path="/home/utility/utilityPlans" /> </li> </Layout.Stack> </React.Fragment> ); }; const UtilityPlans = () => { return ( <React.Fragment> <Heading css={{ padding: '0px $md' }} offset={4} fontWeight="$bold" id="utility-plans-title" > Utility Plans </Heading> <Layout.Stack grow as="ul" aria-labelledby="utility-plans-title" css={{ '&[li]': { listStyle: 'none', margin: 0, padding: 0, }, }} > <li> <NavMenuPrimitives.MenuItem title="Utility Plan 1" description="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vitae lorem posuere augue volutpat tincidunt ut in odio. Sed non vehicula tellus." href="https://abyss.uhc.com/" /> </li> <li> <PageHeaderPrimitives.DrawerLink title="Utility PlanTypes" path="/home/utility/utilityPlans/planTypes" /> </li> </Layout.Stack> </React.Fragment> ); }; const UtilityPlanTypes = () => { return ( <React.Fragment> <Heading css={{ padding: '0px $md' }} offset={4} fontWeight="$bold" id="utility-plan-types-title" > Utility Plan Types </Heading> <Layout.Stack grow space={10} as="ul" aria-describedby="utility-plan-types-title" css={{ marginTop: '$sm', paddingLeft: '$md', '&[li]': { listStyle: 'none', margin: 0, padding: 0, }, }} > <li> <Link css={{ fontWeight: 'bold', fontSize: '16px' }} href="#" variant="custom" > Gas </Link> </li> <li> <Link css={{ fontWeight: 'bold', fontSize: '16px' }} href="#" variant="custom" > Electric </Link> </li> <li> <Link css={{ fontWeight: 'bold', fontSize: '16px' }} href="#" variant="custom" > Water </Link> </li> </Layout.Stack> </React.Fragment> ); }; const DropdownContent = () => { return ( <React.Fragment> <Heading css={{ padding: '0px $md' }} offset={4} fontWeight="$bold" id="section-title" > Dropdown Content </Heading> <Layout.Stack grow as="ul" aria-labelledby="section-title" css={{ padding: 'var(--abyss-space-navMenu-space-paddingVertical-itemLink) var(--abyss-space-navMenu-space-paddingHorizontal-itemLink)', '&[li]': { marginTop: '4px', marginBottom: '4px', }, }} > <li> <NavMenuPrimitives.MenuItem title="Test Link" description="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vitae lorem posuere augue volutpat tincidunt ut in odio. Sed non vehicula tellus." href="https://abyss.uhc.com/" /> </li> <li> <NavMenuPrimitives.MenuItem title="Test Link 2" description="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vitae lorem posuere augue volutpat tincidunt ut in odio. Sed non vehicula tellus." href="https://abyss.uhc.com/" /> </li> </Layout.Stack> </React.Fragment> ); }; return ( <PageHeaderPrimitives.Container css={{ 'abyss-page-header-root': { zIndex: 100, }, }} > <PageHeaderPrimitives.Brandmark logoTitle="Logo Title" /> <PageHeaderPrimitives.HamburgerMenu onClick={() => { setIsOpen(true); }} type="button" aria-label="Menu" aria-haspopup="dialog" > <IconSymbol icon="menu" color="$primary1" />{' '} </PageHeaderPrimitives.HamburgerMenu> <StateRouter.Provider initialPath="/home"> <Drawer isOpen={isOpen} onClose={() => setIsOpen(false)} title="Routing" > <NavMenuPrimitives.RouterHeader /> <StateRouter.Routes> <StateRouter.Route path="/home" title="Drawer Home"> <HomeContent /> </StateRouter.Route> <StateRouter.Route path="/home/utility" title="Utilities"> <UtilityContent /> </StateRouter.Route> <StateRouter.Route path="/home/utility/utilityPlans" title="Utility Plans" > <UtilityPlans /> </StateRouter.Route> <StateRouter.Route path="/home/utility/utilityPlans/planTypes" title="Utility Plan Types" > <UtilityPlanTypes /> </StateRouter.Route> <StateRouter.Route path="/home/sampleContent" title="Dropdown Content" > <DropdownContent /> </StateRouter.Route> </StateRouter.Routes> </Drawer> </StateRouter.Provider> </PageHeaderPrimitives.Container> ); }; ``` ## Primitives This is an example for usage of the `PageHeaderPrimitives` and `NavMenuPrimitives` subcomponents, along with the `StateRouter` implementation. ```jsx live () => { const [isOpen, setIsOpen] = useState(false); const matches = useMediaQuery('(min-width: 1520px)'); const HomeContent = () => { return ( <React.Fragment> <ul> <li> <PageHeaderPrimitives.DrawerLink title="Utility Dropdown" path="/home/utility" onClick={() => { console.log('Utility Dropdown clicked'); }} /> </li> <li> <PageHeaderPrimitives.DrawerLink title="Utility Link" href="https://abyss.uhc.com/" /> </li> <li> <PageHeaderPrimitives.DrawerLink title="Dropdown Menu" path="/home/sampleContent" /> </li> </ul> </React.Fragment> ); }; const UtilityContent = () => { return ( <React.Fragment> <Heading css={{ padding: '0px $md' }} offset={4} fontWeight="$bold" id="utility-items-title" > Utility Items </Heading> <Layout.Stack grow as="ul" aria-labelledby="utility-items-title" css={{ '&[li]': { listStyle: 'none', margin: 0, padding: 0, }, }} > <li> <NavMenuPrimitives.MenuItem title="Test Link" description="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vitae lorem posuere augue volutpat tincidunt ut in odio. Sed non vehicula tellus." href="https://abyss.uhc.com/" /> </li> <li> <NavMenuPrimitives.MenuItem title="Test Link 2" description="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vitae lorem posuere augue volutpat tincidunt ut in odio. Sed non vehicula tellus." href="https://abyss.uhc.com/" /> </li> <li> <PageHeaderPrimitives.DrawerLink title="Utility Plans" path="/home/utility/utilityPlans" /> </li> </Layout.Stack> </React.Fragment> ); }; const UtilityPlans = () => { return ( <React.Fragment> <Heading css={{ padding: '0px $md' }} offset={4} fontWeight="$bold" id="utility-plans-title" > Utility Plans </Heading> <Layout.Stack grow as="ul" aria-labelledby="utility-plans-title" css={{ '&[li]': { listStyle: 'none', margin: 0, padding: 0, }, }} > <li> <NavMenuPrimitives.MenuItem title="Utility Plan 1" description="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vitae lorem posuere augue volutpat tincidunt ut in odio. Sed non vehicula tellus." href="https://abyss.uhc.com/" /> </li> <li> <PageHeaderPrimitives.DrawerLink title="Utility PlanTypes" path="/home/utility/utilityPlans/planTypes" /> </li> </Layout.Stack> </React.Fragment> ); }; const UtilityPlanTypes = () => { return ( <React.Fragment> <Heading css={{ padding: '0px $md' }} offset={4} fontWeight="$bold" id="utility-plan-types-title" > Utility Plan Types </Heading> <Layout.Stack grow space={10} as="ul" aria-describedby="utility-plan-types-title" css={{ marginTop: '$sm', paddingLeft: '$md', '&[li]': { listStyle: 'none', margin: 0, padding: 0, }, }} > <li> <Link css={{ fontWeight: 'bold', fontSize: '16px' }} href="#" variant="custom" > Gas </Link> </li> <li> <Link css={{ fontWeight: 'bold', fontSize: '16px' }} href="#" variant="custom" > Electric </Link> </li> <li> <Link css={{ fontWeight: 'bold', fontSize: '16px' }} href="#" variant="custom" > Water </Link> </li> </Layout.Stack> </React.Fragment> ); }; const DropdownMenuContent = () => { return ( <NavMenuPrimitives.Columns> <NavMenuPrimitives.Column title="Section Title"> <NavMenuPrimitives.MenuItem title="HELLO" href="https://abyss.uhc.com/" > CSS-in-JS with best-in-class developer experience. </NavMenuPrimitives.MenuItem> <NavMenuPrimitives.MenuItem title="GOODBYE" href="https://abyss.uhc.com/" description="Description goes here" /> </NavMenuPrimitives.Column> <NavMenuPrimitives.Column> <NavMenuPrimitives.MenuItem title="Sample onClick" onClick={() => console.log('onClick pressed')} description="A message will be logged to the console when this is clicked." /> </NavMenuPrimitives.Column> <NavMenuPrimitives.Column title="Other Section Title"> <NavMenuPrimitives.MenuItem title="Colors" href="#" description="Description goes here" /> <NavMenuPrimitives.MenuItem title="Colors" href="#" description="Description goes here" /> <NavMenuPrimitives.MenuItem title="Colors" href="#" description="Description goes here" /> </NavMenuPrimitives.Column> </NavMenuPrimitives.Columns> ); }; const DropdownMenuDrawerContent = () => { return ( <React.Fragment> <Heading css={{ padding: '0px $md' }} offset={4} fontWeight="$bold" id="section-title-1" > Section Title </Heading> <Layout.Stack grow as="ul" aria-labelledby="section-title-1" css={{ '&[li]': { listStyle: 'none', margin: 0, padding: 0, }, }} > <li> <NavMenuPrimitives.MenuItem title="HELLO" href="https://abyss.uhc.com/" > CSS-in-JS with best-in-class developer experience. </NavMenuPrimitives.MenuItem> </li> <li> <NavMenuPrimitives.MenuItem title="GOODBYE" href="https://abyss.uhc.com/" > Description goes here </NavMenuPrimitives.MenuItem> </li> <li> <NavMenuPrimitives.MenuItem title="Sample onClick" onClick={() => console.log('onClick pressed')} description="A message will be logged to the console when this is clicked." /> </li> </Layout.Stack> <Heading css={{ padding: '0px $md' }} offset={4} fontWeight="$bold" id="section-title-2" > Other Section Title </Heading> <Layout.Stack grow as="ul" aria-labelledby="section-title-2" css={{ '&[li]': { listStyle: 'none', margin: 0, padding: 0, }, }} > <li> <NavMenuPrimitives.MenuItem title="Colors" href="#" description="Description goes here" /> </li> <li> <NavMenuPrimitives.MenuItem title="Colors" href="#" description="Description goes here" /> </li> <li> <NavMenuPrimitives.MenuItem title="Colors" href="#" description="Description goes here" /> </li> </Layout.Stack> </React.Fragment> ); }; return ( <PageHeaderPrimitives.Provider> <PageHeaderPrimitives.Container> <Layout.Group> <PageHeaderPrimitives.HamburgerMenu onClick={() => { setIsOpen(true); }} type="button" aria-label="Menu" aria-haspopup="dialog" > <IconSymbol icon="menu" color="$primary1" />{' '} </PageHeaderPrimitives.HamburgerMenu> <PageHeaderPrimitives.Brandmark logo={ <Brandmark size="30px" affiliate="uhc" variant="u_mark" color="blue" brand="uhc" /> } logoTitle="UnitedHealthcare" css={{ 'abyss-page-header-logo': { flexShrink: 'inherit', width: 'max-content', }, }} /> </Layout.Group> {matches && ( <Layout.Group space={20}> <NavMenuPrimitives.Root variant="inverted" zIndex={202} hasOverlay> <NavMenuPrimitives.List> <NavMenuPrimitives.Item> <NavMenuPrimitives.Trigger variant="inverted"> Utility Dropdown </NavMenuPrimitives.Trigger> <NavMenuPrimitives.Content> <NavMenuPrimitives.Columns> <NavMenuPrimitives.Column> <NavMenuPrimitives.MenuItem title="Test Link" href="https://abyss.uhc.com/" > Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vitae lorem posuere augue volutpat tincidunt ut in odio. Sed non vehicula tellus. </NavMenuPrimitives.MenuItem> <NavMenuPrimitives.MenuItem title="Test Link 2" href="https://abyss.uhc.com/" > Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vitae lorem posuere augue volutpat tincidunt ut in odio. Sed non vehicula tellus. </NavMenuPrimitives.MenuItem> </NavMenuPrimitives.Column> </NavMenuPrimitives.Columns> </NavMenuPrimitives.Content> </NavMenuPrimitives.Item> <NavMenuPrimitives.Link variant="inverted" href="https://abyss.uhc.com/" > Utility Link </NavMenuPrimitives.Link> <NavMenuPrimitives.Link variant="inverted" href="#"> <Layout.Group space={0}> TrackIt <div style={{ display: 'flex', justifyContent: 'center', alignItems: 'center', height: '14px', width: '14px', borderRadius: '50%', border: 'solid 1px #FFAF1F', backgroundColor: '#FEF7E5', marginLeft: '4px', fontSize: '10px', fontWeight: '700', color: '#002677', }} > 8 </div> </Layout.Group> </NavMenuPrimitives.Link> <NavMenuPrimitives.Link href="#" variant="inverted"> <Layout.Group space={0}> John <div style={{ display: 'flex', justifyContent: 'center', alignItems: 'center', height: '14px', width: '14px', marginLeft: '4px', fontSize: '10px', fontWeight: '$bold', }} > <IconSymbol icon="person" size="$sm" color="$primary1" /> </div> </Layout.Group> </NavMenuPrimitives.Link> </NavMenuPrimitives.List> <NavMenuPrimitives.Viewport /> </NavMenuPrimitives.Root> </Layout.Group> )} <StateRouter.Provider initialPath="/home"> <Drawer isOpen={isOpen} onClose={() => setIsOpen(false)} title="Primitive Menu" > <NavMenuPrimitives.RouterHeader /> <StateRouter.Routes> <StateRouter.Route path="/home" title="Drawer Home"> <HomeContent /> </StateRouter.Route> <StateRouter.Route path="/home/utility" title="Utilities"> <UtilityContent /> </StateRouter.Route> <StateRouter.Route path="/home/utility/utilityPlans" title="Utility Plans" > <UtilityPlans /> </StateRouter.Route> <StateRouter.Route path="/home/utility/utilityPlans/planTypes" title="Utility Plan Types" > <UtilityPlanTypes /> </StateRouter.Route> <StateRouter.Route path="/home/sampleContent" title="Dropdown Content" > <DropdownMenuDrawerContent /> </StateRouter.Route> </StateRouter.Routes> </Drawer> </StateRouter.Provider> </PageHeaderPrimitives.Container> <NavMenuPrimitives.Root hasOverlay> <NavMenuPrimitives.List> <NavMenuPrimitives.Link href="#">Dashboard</NavMenuPrimitives.Link> <NavMenuPrimitives.Item> <NavMenuPrimitives.Trigger>Dropdown Menu</NavMenuPrimitives.Trigger> <NavMenuPrimitives.Content> <DropdownMenuContent /> </NavMenuPrimitives.Content> </NavMenuPrimitives.Item> </NavMenuPrimitives.List> <NavMenuPrimitives.Viewport /> </NavMenuPrimitives.Root> </PageHeaderPrimitives.Provider> ); }; ``` ## Full page layout Click below to see an example of a full page that uses the `PageHeader` component. ```jsx live <Link href="/fullpagelayout" openNewWindow> Full Page Layout </Link> ``` </Tab> <Tab label="PageHeader Dynamic"> ```jsx render <Layout.Stack alignItems="left"> <Alert title="Deprecated"> The dynamic version of the PageHeader component is deprecated and will be removed in version 2.0 of Abyss. This component is in maintenance status and will only receive bugfixes if found. Please migrate your component over to PageHeaderPrimitives </Alert> <h2>Usage</h2> </Layout.Stack> ``` ```jsx live () => { const topMenuItems = [ { title: 'Utility Dropdown', content: ( <NavMenu.Columns> <NavMenu.Column> <NavMenu.Item title="Test Link" description="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vitae lorem posuere augue volutpat tincidunt ut in odio. Sed non vehicula tellus." href="https://abyss.uhc.com/" /> <NavMenu.Item title="Test Link 2" description="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vitae lorem posuere augue volutpat tincidunt ut in odio. Sed non vehicula tellus." href="https://abyss.uhc.com/" /> </NavMenu.Column> </NavMenu.Columns> ), }, { title: 'Utility Link', href: 'https://abyss.uhc.com/', }, { title: ( <Layout.Group space={0}> TrackIt <div style={{ display: 'flex', justifyContent: 'center', alignItems: 'center', height: '14px', width: '14px', borderRadius: '50%', border: 'solid 1px #FFAF1F', backgroundColor: '#FEF7E5', marginLeft: '4px', fontSize: '10px', fontWeight: '700', color: '#002677', }} > 8 </div> </Layout.Group> ), href: '#', }, { title: ( <Layout.Group space={0}> John <div style={{ display: 'flex', justifyContent: 'center', alignItems: 'center', height: '14px', width: '14px', borderRadius: '50%', border: 'solid 1px #002677', marginLeft: '4px', fontSize: '10px', fontWeight: '$bold', }} > <IconSymbol icon="person" size="$sm" /> </div> </Layout.Group> ), href: '#', }, ]; const bottomMenuItems = [ { title: 'Dashboard', href: '#' }, { title: 'Dropdown Menu', content: ( <NavMenu.Columns> <NavMenu.Column title="Section Title"> <NavMenu.Item title="HELLO" href="https://abyss.uhc.com/" description="CSS-in-JS with best-in-class developer experience." /> <NavMenu.Item title="GOODBYE" href="https://abyss.uhc.com/" description="Description goes here" /> </NavMenu.Column> <NavMenu.Column> <NavMenu.Item title="Sample onClick" onClick={() => console.log('onClick pressed')} description="A message will be logged to the console when this is clicked." /> </NavMenu.Column> <NavMenu.Column title="Other Section Title"> <NavMenu.Item title="Colors" href="#" description="Description goes here" /> <NavMenu.Item title="Colors" href="#" description="Description goes here" /> <NavMenu.Item title="Colors" href="#" description="Description goes here" /> </NavMenu.Column> </NavMenu.Columns> ), }, ]; return ( <React.Fragment> <PageHeader topMenuItems={topMenuItems} bottomMenuItems={bottomMenuItems} css={{ 'abyss-page-header-root': { zIndex: 210 } }} /> <Box color="$white" height="100px"> <Label css={{ paddingTop: '$md' }}>Your page content goes here</Label> </Box> </React.Fragment> ); }; ``` ```jsx render <h2>Logo</h2> ``` Use the `logo` prop to provide the logo that will be displayed on the far left side of the header. By default, it will show either the UHC or Optum logo, depending on the page's theme. ```jsx live <PageHeader logoTitle="Default Logo" /> ``` ```jsx live <PageHeader logo={<IconSymbol icon="anchor" size="$lg" />} logoTitle="IconSymbol Logo" /> ``` ```jsx live <PageHeader logo={ <Brandmark brand="uhc" size="$sm" affiliate="uhc" variant="monogram" color="blue" /> } logoTitle="Brandmark Logo" /> ``` ```jsx render <h2>Logo Redirect</h2> ``` Use the `logoRedirect` prop to provide a link that the `logo` will redirect to when clicked. In most cases, you would want this logo to redirect to your website's home page. If a value is not passed in, the logo will not redirect to anything. ```jsx live <PageHeader logoRedirect="https://abyss.uhc.com" logoTitle="Logo Redirect" /> ``` ```jsx render <h2>Logo Title</h2> ``` Use the `logoTitle` prop to specify additional detail about the title of the page. It will be displayed directly to the right of the main logo, with a vertical divider between the logo and the logo title. ```jsx live <PageHeader logoTitle="Logo Title" /> ``` ```jsx render <h2> Hide Logo</h2> ``` Use the `hideLogo` prop to hide the logo. ```jsx live <PageHeader hideLogo>Header Without Logo</PageHeader> ``` ```jsx render <h2> Top and Bottom Menu Items</h2> ``` Use the `bottomMenuItems` and `topMenuItems` props to create navigation bars in the header. - When `bottomMenuItems` is given, it will create a [NavMenu](/web/ui/nav-menu) under the header (this would be traditionally used to provide links for the distinct categories / pages within the website). - When `topMenuItems` is given, it will create a [NavMenu](/web/ui/nav-menu) at the top right of the header (this would be traditionally used for things like login / profile information and links, etc.). Both of these props require the same input structure: an array of objects with the form: ```js { title: node, href: string, onClick: function, content: node, } ``` Each object should have one of `href`, `onClick`, and `content` - if the object has a value for `href` or `onClick`, then in the menu it will be a link to that page, or a button, respectively; if, instead, it has `content` present, in the menu it will be a dropdown menu that, when opened, will display the objects inside `content`. When the window size is too small (ex. on a phone), an expand button will appear on the left side of the header, and these two menus will appear there instead of where they normally do. NOTE: both of these props leverage the [NavMenu](/web/ui/nav-menu) component, so view its documentation [here](/web/ui/nav-menu) for more details on what to pass in for it. ```jsx live () => { const bottomMenuItems = [ { title: 'Bottom Menu Items', href: 'https://abyss.uhc.com', }, { title: 'Sample onClick', onClick: () => console.log('onClick clicked'), }, { title: 'Sample Dropdown 2', content: ( <NavMenu.Columns> <NavMenu.Column> <NavMenu.Item title="Info" href="#" description="This is where you can put links, etc. relevant to the dropdown's title." /> <NavMenu.Item title="Sample onClick" onClick={() => console.log('onClick pressed')} description="A message will be logged to the console when this is clicked." /> </NavMenu.Column> </NavMenu.Columns> ), }, ]; const topMenuItems = [ { title: 'Top Menu Items', href: 'https://abyss.uhc.com', }, { title: 'Sample Dropdown 1', content: ( <NavMenu.Columns> <NavMenu.Column> <NavMenu.Item title="Info" href="#" description="This is where you can put links, etc. relevant to the dropdown's title." /> <NavMenu.Item title="Sample onClick" onClick={() => console.log('onClick pressed')} description="A message will be logged to the console when this is clicked." /> </NavMenu.Column> </NavMenu.Columns> ), }, ]; return ( <React.Fragment> <PageHeader topMenuItems={topMenuItems} bottomMenuItems={bottomMenuItems} css={{ 'abyss-page-header-root': { zIndex: 209 } }} /> <Box color="$white" height="100px"> <Label css={{ padding: '$md' }}>Your page content goes here</Label> </Box> </React.Fragment> ); }; ``` ```jsx render <h2>Disabled NavMenu.Item</h2> ``` Set the `isDisabled` prop to `true` to disable an individual NavMenu.Item. ```jsx live () => { const bottomMenuItems = [ { title: 'Sample Dropdown 2', content: ( <NavMenu.Columns> <NavMenu.Column> <NavMenu.Item title="Info" href="#" description="This is where you can put links, etc. relevant to the dropdown's title." isDisabled /> <NavMenu.Item title="Sample onClick" onClick={() => console.log('onClick pressed')} description="A message will be logged to the console when this is clicked." /> </NavMenu.Column> </NavMenu.Columns> ), }, ]; const topMenuItems = [ { title: 'Sample Dropdown 1', content: ( <NavMenu.Columns> <NavMenu.Column> <NavMenu.Item title="Info" href="#" description="This is where you can put links, etc. relevant to the dropdown's title." isDisabled /> <NavMenu.Item title="Sample onClick" onClick={() => console.log('onClick pressed')} description="A message will be logged to the console when this is clicked." /> </NavMenu.Column> </NavMenu.Columns> ), }, ]; return ( <React.Fragment> <PageHeader topMenuItems={topMenuItems} bottomMenuItems={bottomMenuItems} css={{ 'abyss-page-header-root': { zIndex: 209 } }} /> <Box color="$white" height="100px"> <Label css={{ padding: '$md' }}>Your page content goes here</Label> </Box> </React.Fragment> ); }; ``` ```jsx render <h2>Children</h2> ``` When children are contained inside the Header component, they will be rendered on the right side of the header. If `topMenuItems` is passed in as well, there will be a horizontal divider between the toolbar and the children. To use a pre-formatted design that aligns items horizontally, use the [Header.Toolbar](#headertoolbar) component. ```jsx live <PageHeader> <Text css={{ padding: '$md' }}>Children without topMenuItems</Text> </PageHeader> ``` ```jsx live () => { const topMenuItems = [ { title: 'Sample dropdown menu', content: ( <NavMenu.Columns> <NavMenu.Column> <NavMenu.Item title="Test Link" description="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vitae lorem posuere augue volutpat tincidunt ut in odio. Sed non vehicula tellus." href="https://abyss.uhc.com/" /> <NavMenu.Item title="Test Link 2" description="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vitae lorem posuere augue volutpat tincidunt ut in odio. Sed non vehicula tellus." href="https://abyss.uhc.com/" /> </NavMenu.Column> </NavMenu.Columns> ), }, { title: 'Sample link 2', href: 'https://abyss.uhc.com/', }, ]; return ( <PageHeader topMenuItems={topMenuItems} css={{ 'abyss-page-header-root': { zIndex: 208 } }} > <Text css={{ padding: '$md' }}>Children with topMenuItems</Text> </PageHeader> ); }; ``` ```jsx render <h2> Additional Drawer Content</h2> ``` Use the `extraDrawerContent` prop to add any additional content to the top of the drawer. ```jsx live () => { const bottomMenuItems = [ { title: 'Sample Dropdown 2', content: ( <NavMenu.Columns> <NavMenu.Column> <NavMenu.Item title="Info" href="#" description="This is where you can put links, etc. relevant to the dropdown's title." isDisabled /> <NavMenu.Item title="Sample onClick" onClick={() => console.log('onClick pressed')} description="A message will be logged to the console when this is clicked." /> </NavMenu.Column> </NavMenu.Columns> ), }, ]; const topMenuItems = [ { title: 'Sample Dropdown 1', content: ( <NavMenu.Columns> <NavMenu.Column> <NavMenu.Item title="Info" href="#" description="This is where you can put links, etc. relevant to the dropdown's title." isDisabled /> <NavMenu.Item title="Sample onClick" onClick={() => console.log('onClick pressed')} description="A message will be logged to the console when this is clicked." /> </NavMenu.Column> </NavMenu.Columns> ), }, ]; const modal = useOverlay('pageheader-model'); const MockData = utils.useSearchInputMock(); const form = useForm(); const handleSearch = (data) => { console.log('Searched', data); modal.close(); }; const drawerContent = ( <FormProvider state={form}> <SearchInput placeholder="Search..." label="Search Site" onSearch={handleSearch} isClearable options={MockData} keys={['value']} model="search-input-form" /> </FormProvider> ); return ( <React.Fragment> <PageHeader extraDrawerContent={drawerContent} model="pageheader-model" topMenuItems={topMenuItems} bottomMenuItems={bottomMenuItems} css={{ 'abyss-page-header-root': { zIndex: 209 } }} /> <Box color="$white" height="100px"> <Label css={{ padding: '$md' }}>Your page content goes here</Label> </Box> </React.Fragment> ); }; ``` ```jsx render <h2>Full Width</h2> ``` Use the `fullWidth` prop to set the width of the Header component to full screen. ```jsx live <PageHeader fullWidth> <Text css={{ padding: '$md' }}> Header component will stretch to full screen. </Text> </PageHeader> ``` ```jsx render <h2>Menu Position</h2> ``` Use the `menuPosition` prop to change the position of the hamburger menu and drawer that is shown at smaller view-ports. Set as `right` or `left`. `menuPosition` is set to `left` by default. ```jsx live () => { const topMenuItems = [ { title: 'Sample dropdown menu', content: ( <NavMenu.Columns> <NavMenu.Column> <NavMenu.Item title="Test Link" description="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vitae lorem posuere augue volutpat tincidunt ut in odio. Sed non vehicula tellus." href="https://abyss.uhc.com/" /> <NavMenu.Item title="Test Link 2" description="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vitae lorem posuere augue volutpat tincidunt ut in odio. Sed non vehicula tellus." href="https://abyss.uhc.com/" /> </NavMenu.Column> </NavMenu.Columns> ), }, { title: 'Sample link 2', href: 'https://abyss.uhc.com/', }, ]; return ( <PageHeader topMenuItems={topMenuItems} css={{ 'abyss-page-header-root': { zIndex: 208 } }} menuPosition="right" /> ); }; ``` ```jsx render <h2>Header.Toolbar</h2> ``` Use the `Header.Toolbar` component to render `children` in a pre-formatted layout. When using this component, its children will render horizontally on the far right of the header. You can use multiple `Header.Toolbar`s if you would like multiple lines. ```jsx live <PageHeader> <PageHeader.Toolbar space={10}> <SelectInput label="Profile Option 1" value="Test 1" options={[{ value: 'Test 1', label: 'Test 1' }]} /> <SelectInput label="Profile Option 2" value="Test 2" options={[{ value: 'Test 2', label: 'Test 2' }]} css={{ 'abyss-select-input-root': { marginTop: '0 !important', }, }} /> </PageHeader.Toolbar> </PageHeader> ``` ```jsx live () => { const topMenuItems = [ { title: 'Sample Dropdown Menu', content: ( <NavMenu.Columns> <NavMenu.Column> <NavMenu.Item title="Test Link" description="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vitae lorem posuere augue volutpat tincidunt ut in odio. Sed non vehicula tellus." href="https://abyss.uhc.com/" /> <NavMenu.Item title="Test Link 2" description="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vitae lorem posuere augue volutpat tincidunt ut in odio. Sed non vehicula tellus." href="https://abyss.uhc.com/" /> </NavMenu.Column> </NavMenu.Columns> ), }, { title: 'Sample Link', href: 'https://abyss.uhc.com/', }, ]; return ( <PageHeader topMenuItems={topMenuItems} css={{ 'abyss-page-header-root': { zIndex: 208 } }} > <PageHeader.Toolbar space={10}> <SelectInput label="Profile Option 1" value="Test 1" options={[{ value: 'Test 1', label: 'Test 1' }]} /> <SelectInput label="Profile Option 2" value="Test 2" options={[{ value: 'Test 2', label: 'Test 2' }]} css={{ 'abyss-select-input-root': { marginTop: '0 !important', }, }} /> </PageHeader.Toolbar> </PageHeader> ); }; ``` ```jsx render <h2>Space</h2> ``` Use the `space` prop with `PageHeader.Toolbar` to specify the amount of white space that will separate elements inside the component from each other. The default value is `0`. ```jsx live <PageHeader> <PageHeader.Toolbar space={50}> <SelectInput label="Profile Option 1" value="Test 1" options={[{ value: 'Test 1', label: 'Test 1' }]} /> <SelectInput label="Profile Option 2" value="Test 2" options={[{ value: 'Test 2', label: 'Test 2' }]} css={{ 'abyss-select-input-root': { marginTop: '0 !important', }, }} /> </PageHeader.Toolbar> </PageHeader> ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={PageHeader} rows={[ { name: 'logo', type: 'ReactNode', description: 'The logo component that will be displayed on the left side of the header', }, { name: 'logoRedirect', type: 'string', description: 'A link that the logo will redirect to when clicked', }, { name: 'logoTitle', type: 'string', description: 'Text that will be displayed to the right of the logo', }, { name: 'hideLogo', type: 'boolean', description: 'Flag to hide the logo in the header', }, { name: 'bottomMenuItems', type: 'shape', description: 'The items that will be formatted and displayed in a navigation menu directly under the header', }, { name: 'topMenuItems', type: 'shape', description: 'The items that will be formatted and displayed in a toolbar at the top right of the header', }, { name: 'menuPosition', type: '"left" | "right"', description: 'Sets the position of hamburger menu', }, { name: 'children', type: 'ReactNode', description: 'The items that will be rendered on the right side of the header, under the topMenuItems bar (if it exists)', }, { name: 'fullWidth', type: 'boolean', description: 'Set the width of the header to full screen', }, { name: 'extraDrawerContent', type: 'ReactNode', description: 'The extraDrawerContent of PageHeader', }, { name: 'model', type: 'string', description: 'The model string of PageHeader', }, ]} /> ``` ```jsx render <Docs.PropsTable of={PageHeader.Brandmark} rows={[ { name: 'logo', type: 'ReactNode', description: 'The logo of Page Header Brandmark', }, { name: 'hideLogo', type: 'boolean', description: 'If true , it hides the logo', }, { name: 'logoRedirect', type: 'string', description: 'The link that the logo will redirect to when clicked', }, { name: 'logoTitle', type: 'ReactNode', description: 'The text that will be displayed to the right of the logo', }, ]} /> ``` ```jsx render <Docs.PropsTable of={PageHeader.Drawer} rows={[ { name: 'setDrawerSelection', type: 'function', description: 'selects Drawer for PageHeader', }, { name: 'bottomMenuItems', type: 'array[shape]', description: 'The items that will be formatted and displayed in a navigation menu directly under the PageHeaderDrawer', }, { name: 'topMenuItems', type: 'array[shape]', description: 'The items that will be formatted and displayed in a toolbar at the top right of the PageHeaderDrawer', }, { name: 'maxWindowWidth', type: 'number', description: 'Set the maximum width of the window', }, { name: 'model', type: 'string', description: 'The model string of PageHeaderDrawer', }, { name: 'extraDrawerContent', type: 'ReactNode', description: 'The extraDrawerContent of PageHeaderDrawer', }, { name: 'drawerSelection', type: 'shape', description: 'Selects the drawer for header', }, { name: 'drawerPosition', type: 'left | right', description: 'Sets the position of drawer', }, ]} /> ``` ```jsx render <Docs.PropsTable of={PageHeader.Toolbar} rows={[ { name: 'space', type: 'number', description: 'The number of pixels of white space between each child', }, { name: 'children', type: 'ReactNode', description: 'The elements that will be rendered horizontally', }, ]} /> ``` ```jsx render <Docs.PropsTable of={PageHeaderPrimitives.Container} rows={[ { name: 'fullWidth', type: 'boolean', description: 'Set the width of the container to full screen', }, { name: 'ref', type: 'object', description: 'Ref to header root element', }, ]} /> ``` ```jsx render <Docs.PropsTable of={PageHeaderPrimitives.DrawerLink} rows={[ { name: 'title', type: 'string', description: 'The title of the DrawerLink', }, { name: 'href', type: 'string', description: 'The URL (internal/external) of the DrawerLink', }, { name: 'path', type: 'string', description: 'The path used to navigate the StateRouter', }, { name: 'onClick', type: 'string', description: 'Used to trigger a custom function when the DrawerLink is clicked', }, ]} /> ``` ```jsx render <Docs.PropsTable of={StateRouter.Provider} rows={[ { name: 'children', type: 'ReactNode', description: 'The content of the StateRouter Provider', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={PageHeader} rows={[ { name: 'page-header-root', description: 'Header root element', }, { name: 'page-header-container', description: 'Container for the main section of the header (everything except the bottom NavMenu)', }, { name: 'page-header-expand-button', description: 'Button to expand the side drawer when screen size is too small', }, { name: 'page-header-logo', description: 'Logo displayed on the left of the header', }, { name: 'page-header-logo-title', description: 'Title displayed next to logo', }, { name: 'page-header-top-nav-menu', description: 'Container for the navigation menu at the top right of the header', }, { name: 'page-header-bottom-nav-menu', description: 'Container for the navigation menu at the bottom of the header', }, { name: 'page-header-heading-text-container', description: 'Container for the heading text that displays additional detail about the title of the page', }, { name: 'page-header-vertical-rule', description: 'Vertical rule that divides header logo and logo title', }, { name: 'page-header-content', description: 'Content for header', }, { name: 'page-header-toolbars', description: 'Header toolbars', }, { name: 'page-header-horizontal-rule', description: 'Horizontal rule that divides items in header toolbar', }, { name: 'page-header-drawer-horizontal-rule', description: 'Horizontal rule that divides items in drawer', }, { name: 'page-header-drawer-menu-main', description: 'Main header drawer menu', }, { name: 'page-header-drawer-menu-sub', description: 'Sub header drawer menu', }, { name: 'page-header-drawer-menu-item', description: 'Header drawer menu item', }, { name: 'page-header-drawer-menu-item-button', description: 'Header drawer menu item', }, { name: 'page-header-drawer-back-button-container', description: 'Container for back button in header drawer', }, { name: 'page-header-drawer-selected-menu-name', description: 'Container for selected menu in header', }, { name: 'page-header-drawer-header-container', description: 'Container for drawer header', }, { name: 'page-header-drawer-selection-container', description: 'Container for drawer selection content', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={PageHeader.Brandmark} rows={[ { name: 'page-header-logo', description: 'Page Header Logo', }, { name: 'page-header-vertical-rule', description: 'Page Header Vertical Rule', }, { name: 'page-header-logo-title', description: 'Page Header Logo Title', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={PageHeader.Drawer} rows={[ { name: 'page-header-expand-button', description: 'Page Header Expand Button', }, { name: 'page-header-drawer-menu-main', description: 'Page Header Drawer Menu Main ', }, { name: 'page-header-drawer-horizontal-rule', description: 'Page Header Drawer Horizontal Rule', }, { name: 'page-header-drawer-menu-sub', description: 'Page Header Drawer Sub Menu ', }, { name: 'page-header-drawer-header', description: 'Page Header Drawer Header', }, { name: 'page-header-drawer-back-button-container', description: 'Page Header Drawer Back Button Container', }, { name: 'page-header-horizontal-rule', description: 'Page Header Horizontal Rule', }, { name: 'page-header-drawer-selected-menu-name', description: 'Page Header Drawer Selected Menu Name', }, { name: 'page-header-drawer-selection-content', description: 'Page Header Drawer Selection Content', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={PageHeader.Toolbar} rows={[ { name: 'page-header-toolbar-root', description: 'Toolbar root element', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={PageHeaderPrimitives.Container} rows={[ { name: 'page-header-root', description: 'Header root element', }, { name: 'page-header-container', description: 'Container for the main section of the header (everything except the bottom NavMenu)', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={PageHeaderPrimitives.DrawerLink} rows={[ { name: 'page-header-drawer-menu-item-button', description: 'Button element that contains the DrawerLink', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={PageHeaderPrimitives.HamburgerMenu} rows={[ { name: 'page-header-expand-button', description: 'Button to expand the side drawer', }, ]} /> ``` </Tab> <Tab label="Accessibility"> ```jsx live () => { const [isOpen, setIsOpen] = useState(false); const matches = useMediaQuery('(min-width: 1520px)'); const HomeContent = () => { return ( <React.Fragment> <ul> <li> <PageHeaderPrimitives.DrawerLink title="About Abyss" path="/home/utility" onClick={() => { console.log('Utility Dropdown clicked'); }} /> </li> <li> <PageHeaderPrimitives.DrawerLink title="Abyss home" href="https://abyss.uhc.com/" /> </li> <li> <PageHeaderPrimitives.DrawerLink title="Abyss Components" path="/home/sampleContent" /> </li> </ul> </React.Fragment> ); }; const UtilityContent = () => { return ( <React.Fragment> <Heading css={{ padding: '0px $md' }} offset={4} fontWeight="$bold" id="utility-items-title" > About Abyss </Heading> <Layout.Stack grow as="ul" aria-labelledby="utility-items-title" css={{ '&[li]': { listStyle: 'none', margin: 0, padding: 0, }, }} > <li> <NavMenuPrimitives.MenuItem title="About Abyss" description="What is Abyss? How does it work? Who are we?" href="https://abyss.uhc.com/web/about/" /> </li> <li> <PageHeaderPrimitives.DrawerLink title="Accessibility" path="/home/utility/utilityPlans" /> </li> </Layout.Stack> </React.Fragment> ); }; const UtilityPlans = () => { return ( <React.Fragment> <Heading css={{ padding: '0px $md' }} offset={4} fontWeight="$bold" id="utility-plans-title" > Abyss accessibility </Heading> <Layout.Stack grow as="ul" aria-labelledby="utility-plans-title" css={{ '&[li]': { listStyle: 'none', margin: 0, padding: 0, }, }} > <li> <NavMenuPrimitives.MenuItem title="Accessibility" description="We have some information about Abyss accessibility you may want to read." href="https://abyss.uhc.com/web/accessibility/" /> </li> <li> <PageHeaderPrimitives.DrawerLink title="WAI-ARIA Information" path="/home/utility/utilityPlans/planTypes" /> </li> </Layout.Stack> </React.Fragment> ); }; const UtilityPlanTypes = () => { return ( <React.Fragment> <Heading css={{ padding: '0px $md' }} offset={4} fontWeight="$bold" id="utility-plan-types-title" > WAI-ARIA information </Heading> <Layout.Stack grow space={10} as="ul" aria-describedby="utility-plan-types-title" css={{ marginTop: '$sm', paddingLeft: '$md', '&[li]': { listStyle: 'none', margin: 0, padding: 0, }, }} > <li> <Link css={{ fontWeight: 'bold', fontSize: '16px' }} href="https://www.w3.org/WAI/ARIA/apg/" variant="custom" > WAI-ARIA Practices Guide 1.1 </Link> </li> <li> <Link css={{ fontWeight: 'bold', fontSize: '16px' }} href="https://www.w3.org/WAI/ARIA/apg/patterns/" variant="custom" > WAI-ARIA Patterns </Link> </li> <li> <Link css={{ fontWeight: 'bold', fontSize: '16px' }} href="https://www.w3.org/TR/using-aria/" variant="custom" > The Rules of ARIA (Using ARIA) </Link> </li> </Layout.Stack> </React.Fragment> ); }; const DropdownMenuContent = () => { return ( <NavMenuPrimitives.Columns> <NavMenuPrimitives.Column title="Abyss components"> <NavMenuPrimitives.MenuItem title="Abyss web" href="https://abyss-test.uhc.com/web/overview/" description="Check out the Abyss web components" /> <NavMenuPrimitives.MenuItem title="Abyss mobile" href="https://abyss.uhc.com/mobile/overview/" > Abyss also does mobile native - iOS and Android! </NavMenuPrimitives.MenuItem> </NavMenuPrimitives.Column> <NavMenuPrimitives.Column> <NavMenuPrimitives.MenuItem title="Click events?" onClick={() => console.log('onClick pressed')} description="Yes! Click this to see a message logged to the console." /> </NavMenuPrimitives.Column> <NavMenuPrimitives.Column title="What's your role?"> <NavMenuPrimitives.MenuItem title="Designer?" href="https://abyss.uhc.com/web/designers/design-kit/" description="Check out our design kit" /> <NavMenuPrimitives.MenuItem title="Web developer?" href="https://abyss.uhc.com/web/developers/overview/" description="Start with our devloper overview" /> <NavMenuPrimitives.MenuItem title="Marketing?" href="https://abyss.uhc.com/web/brand/uhc/get-started/" description="We support UHC brands" /> </NavMenuPrimitives.Column> </NavMenuPrimitives.Columns> ); }; const DropdownMenuDrawerContent = () => { return ( <React.Fragment> <Heading css={{ padding: '0px $md' }} offset={4} fontWeight="$bold" id="section-title-1" > Abyss Components </Heading> <Layout.Stack grow as="ul" aria-labelledby="section-title-1" css={{ '&[li]': { listStyle: 'none', margin: 0, padding: 0, }, }} > <li> <NavMenuPrimitives.MenuItem title="Abyss web" href="https://abyss-test.uhc.com/web/overview/" description="Check out the Abyss web components" /> </li> <li> <NavMenuPrimitives.MenuItem title="Abyss mobile" href="https://abyss.uhc.com/mobile/overview/" > Abyss also does mobile native - iOS and Android! </NavMenuPrimitives.MenuItem> </li> <li> <NavMenuPrimitives.MenuItem title="Click events?" onClick={() => console.log('onClick pressed')} description="Yes! Click this to see a message logged to the console." /> </li> </Layout.Stack> <Heading css={{ padding: '0px $md' }} offset={4} fontWeight="$bold" id="section-title-2" > What's your role? </Heading> <Layout.Stack grow as="ul" aria-labelledby="section-title-2" css={{ '&[li]': { listStyle: 'none', margin: 0, padding: 0, }, }} > <li> <NavMenuPrimitives.MenuItem title="Designer?" href="https://abyss.uhc.com/web/designers/design-kit/" description="Check out our design kit" /> </li> <li> <NavMenuPrimitives.MenuItem title="Web developer?" href="https://abyss.uhc.com/web/developers/overview/" description="Start with our devloper overview" /> </li> <li> <NavMenuPrimitives.MenuItem title="Marketing?" href="https://abyss.uhc.com/web/brand/uhc/get-started/" description="We support UHC brands" /> </li> </Layout.Stack> </React.Fragment> ); }; return ( <PageHeaderPrimitives.Provider> <PageHeaderPrimitives.Container> <Layout.Group> <PageHeaderPrimitives.HamburgerMenu onClick={() => { setIsOpen(true); }} type="button" aria-label="Menu" aria-haspopup="dialog" > <IconSymbol icon="menu" color="$primary1" />{' '} </PageHeaderPrimitives.HamburgerMenu> <PageHeaderPrimitives.Brandmark logo={ <Brandmark size="30px" affiliate="uhc" variant="u_mark" color="blue" brand="uhc" /> } logoTitle="The World of Abyss" css={{ 'abyss-page-header-logo': { flexShrink: 'inherit', width: 'max-content', }, }} /> </Layout.Group> {matches && ( <Layout.Group space={20}> <NavMenuPrimitives.Root variant="inverted" zIndex={202} hasOverlay> <NavMenuPrimitives.List> <NavMenuPrimitives.Item> <NavMenuPrimitives.Trigger variant="inverted"> Accessibility </NavMenuPrimitives.Trigger> <NavMenuPrimitives.Content> <NavMenuPrimitives.Columns> <NavMenuPrimitives.Column> <NavMenuPrimitives.MenuItem title="Accessibility" href="https://abyss.uhc.com/web/accessibility/" > We have some information about Abyss accessibility you may want to read. </NavMenuPrimitives.MenuItem> <NavMenuPrimitives.MenuItem title="WAI-ARIA Patterns" href="https://www.w3.org/WAI/ARIA/apg/patterns/" > Many of our components are based upon these patterns </NavMenuPrimitives.MenuItem> </NavMenuPrimitives.Column> </NavMenuPrimitives.Columns> </NavMenuPrimitives.Content> </NavMenuPrimitives.Item> <NavMenuPrimitives.Link variant="inverted" href="https://uhgazure.sharepoint.com/sites/accessibility-knowledge-center/" > ACOE Resources </NavMenuPrimitives.Link> </NavMenuPrimitives.List> <NavMenuPrimitives.Viewport /> </NavMenuPrimitives.Root> </Layout.Group> )} <StateRouter.Provider initialPath="/home"> <Drawer isOpen={isOpen} onClose={() => setIsOpen(false)} title="The World of Abyss" > <NavMenuPrimitives.RouterHeader /> <StateRouter.Routes> <StateRouter.Route path="/home" title="Main menu"> <HomeContent /> </StateRouter.Route> <StateRouter.Route path="/home/utility" title="About Abyss"> <UtilityContent /> </StateRouter.Route> <StateRouter.Route path="/home/utility/utilityPlans" title="Abyss Accessibility" > <UtilityPlans /> </StateRouter.Route> <StateRouter.Route path="/home/utility/utilityPlans/planTypes" title="WAI-ARIA Information" > <UtilityPlanTypes /> </StateRouter.Route> <StateRouter.Route path="/home/sampleContent" title="Dropdown Content" > <DropdownMenuDrawerContent /> </StateRouter.Route> </StateRouter.Routes> </Drawer> </StateRouter.Provider> </PageHeaderPrimitives.Container> <NavMenuPrimitives.Root hasOverlay> <NavMenuPrimitives.List> <NavMenuPrimitives.Link href="#">Home</NavMenuPrimitives.Link> <NavMenuPrimitives.Item> <NavMenuPrimitives.Trigger>Components</NavMenuPrimitives.Trigger> <NavMenuPrimitives.Content> <DropdownMenuContent /> </NavMenuPrimitives.Content> </NavMenuPrimitives.Item> </NavMenuPrimitives.List> <NavMenuPrimitives.Viewport /> </NavMenuPrimitives.Root> </PageHeaderPrimitives.Provider> ); }; ``` <h3> Reduced Motion </h3> Animations and transitions that have been changed when a user has `prefers-reduced-motion` set to `reduced`: - Transition upon opening `PageHeader.Drawer` is removed ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Tab', description: 'Moves focus to the next focusable element', }, { name: 'Enter', description: 'If the logo is selected, redirects to the specified link. If focus is inside the navigation menu, redirects to the link if the menu bar item is a redirect, or opens the relevant dropdown menu if the item has one', }, { name: 'Space', description: 'If focus on a menu bar item with a dropdown, opens the relevant dropdown menu', }, { name: 'Left Arrow', description: 'When focus is inside one of the navigation menus, focuses the previous menu bar item', }, { name: 'Up Arrow', description: 'When focus is inside one of the navigation menus, focuses the previous menu bar item', }, { name: 'Right Arrow', description: 'When focus is inside one of the navigation menus, focuses the next menu bar item', }, { name: 'Down Arrow', description: 'When focus is inside one of the navigation menus, focuses the next menu bar item. If focus is on an open menu bar item, moves focus into its dropdown menu', }, { name: 'Escape', description: 'Closes open dropdown menu and moves focus to its menu bar item', }, { name: 'Home', description: 'If inside a navigation menu, moves focus to the first item in the menu', }, { name: 'End', description: 'If inside a navigation menu, moves focus to the last item in the menu', }, ]} /> ``` </Tab> --- id: pagination-v2 category: Navigation title: V2Pagination description: Navigates between a set number of pages. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=10540-2403 subDirectory: Pagination/v2/Pagination sourceIsTS: true --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="Pagination"></Docs.V2MigrationBanner> ``` ```jsx import { V2Pagination } from '@uhg-abyss/web/ui/Pagination'; ``` ## V2Pagination Pass the `pages` variable into the `usePaginationV2` hook to match how many pages you would like to display. Find additional resources on `usePaginationV2` [here](/web/hooks/use-pagination-v2). Examples of pagination being used can be seen in [DataTable](/web/ui/data-table) and [Search Results](/web/ui/search-results). ```jsx live () => { const { state, setData, firstPage, lastPage, ...paginationProps } = usePaginationV2({ pages: 10 }); return ( <Layout.Stack space={16} grow css={{ overflow: 'auto' }}> <Text fontWeight="bold" size="18px"> Page {state.currentPage} </Text> <V2Pagination {...paginationProps} /> <pre> {JSON.stringify( { state, setData, firstPage, lastPage, ...paginationProps }, null, 2 )} </pre> </Layout.Stack> ); }; ``` ## Variants Use the `variant` prop to change the format of the pagination display. Possible options are `minimal` and `extended`, and the default value is `extended`. ```jsx live () => { const { state, setData, firstPage, lastPage, ...paginationProps } = usePaginationV2({ pages: 10 }); return ( <Layout.Stack space={16} grow css={{ overflow: 'auto' }}> <Text fontWeight="bold" size="18px"> Page {state.currentPage} (Minimal Variant) </Text> <V2Pagination {...paginationProps} variant="minimal" /> <Text fontWeight="bold" size="18px"> Page {state.currentPage} (Extended Variant - Default) </Text> <V2Pagination {...paginationProps} /> </Layout.Stack> ); }; ``` ## PageSize ```jsx import { V2PageSize } from '@uhg-abyss/web/ui/Pagination'; ``` `V2PageSize` component is used to change how many rows to display per page. For an example of its usage, see the [DataTable docs](/web/ui/data-table). Its props are: - `pageSizeOptions`: The possible values for the dropdown. The default value is `[10, 15, 20]`. - `pageSize`: The current selected value from the `pageSizeOptions`. This prop is required. - `setPageSize`: Function to set the current value of the `pageSize` prop. This prop is required. ```jsx live () => { const pageSizeOptions = [10, 15, 20]; const [pageSize, setPageSize] = useState(10); return ( <React.Fragment> <V2PageSize pageSizeOptions={pageSizeOptions} pageSize={pageSize} setPageSize={setPageSize} /> </React.Fragment> ); }; ``` ## V2Results ```jsx import { V2Results } from '@uhg-abyss/web/ui/Pagination'; ``` The `V2Results` component can display information about the data being displayed. For an example of its usage, see the [DataTable docs](/web/ui/data-table). Its props are: - `pageIndex`: The current page index in the pagination. This prop is required. - `pageSize`: The current size per page. This prop is required. - `resultsTotalCount`: The total number of rows in data set. This prop is required. ```jsx live () => { const pageSize = 5; const numPages = 10; const { state, setData, firstPage, lastPage, ...paginationProps } = usePaginationV2({ pages: numPages, pageSize }); return ( <Layout.Stack grow css={{ overflow: 'auto' }}> <V2Results pageIndex={paginationProps.pageIndex} resultsTotalCount={numPages * pageSize} pageSize={pageSize} /> <V2Pagination {...paginationProps} /> </Layout.Stack> ); }; ``` ### Additional text Use the `additionalText` prop to display additional information underneath the text. ```jsx live () => { const { pageIndex, ...paginationProps } = usePaginationV2({ pages: 2 }); return ( <V2Results pageIndex={pageIndex} resultsTotalCount={10} pageSize={5} additionalText="(Can insert extra text here)" /> ); }; ``` ## V2RowCount ```jsx import { V2RowCount } from '@uhg-abyss/web/ui/Pagination'; ``` The `V2RowCount` component displays how many rows are currently on the page. For an example of its usage, see the [DataTable docs](/web/ui/data-table). Its props are: - `rowCount`: The number of rows currently being displayed to the user. This prop is required. ```jsx live () => { const searchResults = [ { id: 1 }, { id: 2 }, { id: 3 }, { id: 4 }, { id: 5 }, { id: 6 }, { id: 7 }, ]; const { state: { rowCount }, } = usePaginationV2({ data: searchResults, pages: 10, pageSize: 2 }); return ( <React.Fragment> <V2RowCount rowCount={rowCount} /> </React.Fragment> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2Pagination" propTypeName="PaginationProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="V2PageSize" propTypeName="PageSizeProps" /> ``` ```jsx render <Docs.V2WebPropsTable title="V2RowCount" propTypeName="RowCountProps" /> ``` ```jsx render <Docs.V2WebPropsTable title="V2Results" propTypeName="ResultsProps" /> ``` ```jsx render <Docs.V2ClassesTable title="V2Pagination" classes={[PaginationClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2PageSize" classes={[PageSizeClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2RowCount" classes={[RowCountClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2Results" classes={[ResultsClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> The pagination root container(`nav`) must have a descriptive accessible name. For example, if the pagination control is used for a table, the accessible name might be “table“ pagination. If the pagination control is used for search results, the accessible name might be “search results“ pagination. ```jsx live () => { const paginationProps = usePaginationV2({ pages: 10 }); const paginationProps2 = usePaginationV2({ pages: 10 }); const paginationProps3 = usePaginationV2({ pages: 10 }); const { data } = utils.useDocDataTable(5, 4); const pageSizeOptions = [10, 15, 20]; const [pageSize, setPageSize] = useState(10); return ( <Layout.Stack space={16} grow css={{ overflow: 'auto' }}> <Text fontWeight="bold" size="18px"> <span role="alert">Page {paginationProps.state.currentPage} </span> (Extended Variant - Default) with V2Results </Text> <V2Pagination {...paginationProps} label="Extended pagination" /> <Text fontWeight="bold" size="18px"> Page {paginationProps2.state.currentPage} (Minimal Variant) </Text> <V2Pagination {...paginationProps2} variant="minimal" label="Minimal pagination" /> <Text fontWeight="bold" size="18px"> V2PageSize </Text> <V2PageSize pageSizeOptions={pageSizeOptions} pageSize={pageSize} setPageSize={setPageSize} /> <Text fontWeight="bold" size="18px"> V2Results </Text> <div role="alert"> <V2Pagination {...paginationProps3} variant="minimal" label="Minimal results pagination" /> <V2Results {...paginationProps3} resultsTotalCount={20} pageSize={2} /> </div> </Layout.Stack> ); }; ``` #### Accepted BrAT Variant Behaviors - ALL (JAWS, NVDA, VoiceOver) - Announce status update "X of Y" when changing pages - “X of Y” announced in normal reading order between [ < ] and [ > ] - JAWS - Correctly announces "list of 2 items" - Does not announce "X of Y" as part of `<nav>` on focus - NVDA, VoiceOver (Mac) - Incorrectly announces "list of 3 items" - Does announce "X of Y" as part of `<nav>` on focus </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={Pagination} keys={['paginationV2']} /> ``` </Tab> --- id: pagination category: Navigation title: Pagination description: Navigates between a set number of pages. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=0-1564 subDirectory: Pagination/v1/Pagination --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="Pagination"></Docs.V2MigrationBanner> ``` ```jsx import { Pagination } from '@uhg-abyss/web/ui/Pagination'; ``` ## Pagination Pass the `pages` variable into the `usePagination` hook to match how many pages you would like to display. Find additional resources on `usePagination` [here](/web/hooks/use-pagination). Examples of pagination being used can be seen in [DataTable](/web/ui/data-table) and [Search Results](/web/ui/search-results). ```jsx live () => { const paginationProps = usePagination({ pages: 10 }); return ( <React.Fragment> <Card> <Card.Title>Page {paginationProps.state.currentPage}</Card.Title> <Card.Section> <Pagination {...paginationProps} /> </Card.Section> </Card> <pre>{JSON.stringify(paginationProps, null, 2)}</pre> </React.Fragment> ); }; ``` ## Methods `previousPage`, `gotoPage`, and `nextPage` are methods to let pagination know how to navigate to certain pages. ```jsx live () => { const { gotoPage, previousPage, nextPage, state, ...paginationProps } = usePagination({ pages: 10, }); const { currentPage } = state; return ( <Card> <Card.Title>Page {currentPage}</Card.Title> <Card.Section> <Pagination {...paginationProps} gotoPage={gotoPage} previousPage={previousPage} nextPage={nextPage} /> </Card.Section> </Card> ); }; ``` ## Boolean checks `canPreviousPage` and `canNextPage` are used to check if the previous or next page is accessible given the current page index. ```jsx live () => { const { canPreviousPage, canNextPage, state, ...paginationProps } = usePagination({ pages: 10 }); const { currentPage, pageCount } = state; return ( <Card> <Card.Title>Page {currentPage}</Card.Title> <Card.Section> <Pagination {...paginationProps} canPreviousPage={canPreviousPage} canNextPage={canNextPage} /> </Card.Section> </Card> ); }; ``` ## Variants Use the `variant` prop to change the format of the pagination display. Possible options are `compact` and `extended`, and the default value is `extended`. ```jsx live () => { const paginationProps = usePagination({ pages: 10 }); return ( <Card> <Card.Title> Page {paginationProps.state.currentPage} (Compact Variant) </Card.Title> <Card.Section> <Pagination {...paginationProps} variant="compact" /> </Card.Section> </Card> ); }; ``` ```jsx live () => { const paginationProps = usePagination({ pages: 10 }); return ( <Card> <Card.Title> Page {paginationProps.state.currentPage} (Extended Variant - Default) </Card.Title> <Card.Section> <Pagination {...paginationProps} /> </Card.Section> </Card> ); }; ``` ## PageSize ```jsx import { PageSize } from '@uhg-abyss/web/ui/Pagination'; ``` `PageSize` component is used to change how many rows to display per page. For an example of its usage please visit [Data Table](/web/ui/data-table). Its props are: - `pageSizeOptions`: The possible values for the dropdown. The default value is `[10, 15, 20]`. - `pageSize`: The current selected value from the `pageSizeOptions`. This prop is required. - `setPageSize`: Function to set the current value of the `pageSize` prop. This prop is required. - `customResultsLabel`: Ability to change the default 'Results' label. ```jsx live () => { const pageSizeOptions = [10, 15, 20]; const [pageSize, setPageSize] = useState(10); return ( <React.Fragment> <PageSize pageSizeOptions={pageSizeOptions} pageSize={pageSize} setPageSize={setPageSize} /> </React.Fragment> ); }; ``` ## ResultCount ```jsx import { ResultCount } from '@uhg-abyss/web/ui/Pagination'; ``` The `ResultCount` component can display information about the data being displayed. For an example of its usage please visit [Data Table](/web/ui/data-table). Its props are: - `pageIndex`: The current page index in the pagination. This prop is required. - `pageSize`: The current size per page. This prop is required. - `resultsTotalCount`: The total number of rows in data set. This prop is required. - `customResultsLabel`: Ability to change the default 'Results' label. ```jsx live () => { const paginationProps = usePagination({ pages: 10 }); const { data } = utils.useDocDataTable(5, 4); return ( <React.Fragment> <ResultCount {...paginationProps} resultsTotalCount={data.length} pageSize={5} /> </React.Fragment> ); }; ``` ### Additional text Use the `additionalText` prop to display additional information underneath the text. ```jsx live () => { const paginationProps = usePagination({ pages: 10 }); const { data } = utils.useDocDataTable(5, 4); return ( <React.Fragment> <ResultCount additionalText="(Can insert extra text here)" {...paginationProps} resultsTotalCount={data.length} pageSize={5} /> </React.Fragment> ); }; ``` ## Custom results label Use the `customResultsLabel` prop in the `ResultCount` or `PageSize` component to change the default 'Results' label. ```jsx live () => { const paginationProps = usePagination({ pages: 10 }); const { data } = utils.useDocDataTable(5, 4); const pageSizeOptions = [10, 15, 20]; const [pageSize, setPageSize] = useState(10); return ( <Layout.Stack alignItems="left" space={20}> <PageSize pageSizeOptions={pageSizeOptions} pageSize={pageSize} setPageSize={setPageSize} customResultsLabel="Records" /> <ResultCount {...paginationProps} resultsTotalCount={data.length} pageSize={5} customResultsLabel="records" /> </Layout.Stack> ); }; ``` ## RowCount ```jsx import { RowCount } from '@uhg-abyss/web/ui/Pagination'; ``` The `RowCount` component displays how many rows are currently on the page. For an example of its usage please visit [Data Table](/web/ui/data-table). Its props are: - `rowCount`: The number of rows currently being displayed to the user. This prop is required. ```jsx live () => { const searchResults = [ { id: 1 }, { id: 2 }, { id: 3 }, { id: 4 }, { id: 5 }, { id: 6 }, { id: 7 }, ]; const { state: { rowCount }, } = usePagination({ data: searchResults, pages: 10, pageSize: 2 }); return ( <React.Fragment> <RowCount rowCount={rowCount} /> </React.Fragment> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={Pagination} rows={[ { name: 'previousPage', type: 'function', description: 'Method to go to previous page', }, { name: 'canPreviousPage', type: 'boolean', description: 'Flag to check if previous page exists', }, { name: 'pageIndex', type: 'number', description: 'Index of page', }, { name: 'gotoPage', type: 'function', description: 'Function to go to a page', }, { name: 'pageCount', type: 'number', description: 'Number of pages', }, { name: 'nextPage', type: 'function', description: 'Method to go to next page', }, { name: 'canNextPage', type: 'boolean', description: 'Flag to check if next page exists', }, { name: 'variant', type: "'compact' | 'extended'", description: 'Variant for pagination display', }, { name: 'customPreviousLabel', type: 'string', description: 'Change the default "Previous" label', default: 'Previous', }, { name: 'customNextLabel', type: 'string', description: 'Change the default "Next" label', default: 'Next', }, ]} /> ``` ```jsx render <Docs.PropsTable of={PageSize} rows={[ { name: 'pageSize', type: 'number', description: 'Set the page size', }, { name: 'setPageSize', type: 'function', description: 'Function to set page size', }, { name: 'pageSizeOptions', type: 'array[number]', description: 'Default page size options', }, { name: 'customResultsLabel', type: 'string', description: 'Change the default "Results" label', default: 'Results', }, { name: 'customPerPageLabel', type: 'string', description: 'Change the default "per page" label', default: 'per page', }, ]} /> ``` ```jsx render <Docs.PropsTable of={RowCount} rows={[ { name: 'rowCount', type: 'number', description: 'number of rows in the current page', }, ]} /> ``` ```jsx render <Docs.PropsTable of={ResultCount} rows={[ { name: 'pageIndex', type: 'number', description: 'Index of page', }, { name: 'pageSize', type: 'number', description: 'Set the page size', }, { name: 'additionalText', type: 'string', description: 'Additional text to display', }, { name: 'resultsTotalCount', type: 'number', description: 'Total row count', }, { name: 'customResultsLabel', type: 'string', description: 'Change the default "Results" label', default: 'Results', }, { name: 'customShowingLabel', type: 'string', description: 'Change the default "Showing" label', default: 'Showing', }, { name: 'customOfLabel', type: 'string', description: 'Change the default "of" label', default: 'of', }, { name: 'customResultLabel', type: 'string', description: 'Change the default "Result" label', default: 'Result', }, { name: 'customNoResultsLabel', type: 'string', description: 'Change the default "No results found" message', default: 'No results found', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Pagination} rows={[ { name: 'pagination-root', description: 'Pagination root element', }, { name: 'pagination-container', description: 'Pagination container', }, { name: 'pagination-text', description: 'Pagination TextInput', }, { name: 'pagination-button', description: 'Pagination Button', }, { name: 'pagination-page-button', description: 'Page Button', }, { name: 'pagination-ellipsis', description: 'Pagination ellipsis', }, { name: 'pagination-abbreviated-container', description: 'Pagination abbreviated container', }, { name: 'pagination-arrow', description: 'Pagination arrow icon', }, { name: 'pagination-icon-left', description: 'Pagination left arrow icon', }, { name: 'pagination-text-left', description: 'Pagination previous button text', }, { name: 'pagination-divider', description: 'Pagination divider', }, { name: 'pagination-text-right', description: 'Pagination next button text', }, { name: 'pagination-icon-right', description: 'Pagination right arrow icon', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={PageSize} rows={[ { name: 'pagination-page-size-root', description: 'Page size root element', }, { name: 'pagination-page-size-label', description: 'Label', }, { name: 'pagination-page-size-select-list', description: 'Select List', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={ResultCount} rows={[ { name: 'pagination-results-root', description: 'Pagination results root element', }, { name: 'pagination-results-text', description: 'Text', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={RowCount} rows={[ { name: 'pagination-row-count-root', description: 'Pagination RowCount root element', }, { name: 'pagination-row-count-text', description: 'Pagination RowCount text element', }, ]} /> ``` </Tab> <Tab label="Accessibility"> The pagination root container(`nav`) must have a descriptive accessible name. For example, if the pagination control is used for a table, the accessible name might be “table“ pagination. If the pagination control is used for search results, the accessible name might be “search results“ pagination. Use the `ariaLabel` prop to provide your pagination root container with an accessibile `aria-label`. ```jsx live () => { const paginationProps = usePagination({ pages: 10 }); const paginationProps2 = usePagination({ pages: 10 }); const paginationProps3 = usePagination({ pages: 10 }); const { data } = utils.useDocDataTable(5, 4); const pageSizeOptions = [10, 15, 20]; const [pageSize, setPageSize] = useState(10); return ( <Card> <Card.Title> Page {paginationProps.state.currentPage} (Extended Variant - Default) </Card.Title> <Card.Section> <Pagination {...paginationProps} ariaLabel="Extended Pagination" /> </Card.Section> <Card.Title> Page {paginationProps2.state.currentPage} (Compact Variant) </Card.Title> <Card.Section> <Pagination {...paginationProps2} variant="compact" ariaLabel="Compact Pagination" /> </Card.Section> <Card.Title>PageSize</Card.Title> <Card.Section> <PageSize pageSizeOptions={pageSizeOptions} pageSize={pageSize} setPageSize={setPageSize} customResultsLabel="Records" /> </Card.Section> <Card.Title>ResultCount</Card.Title> <Card.Section> <ResultCount {...paginationProps3} resultsTotalCount={data.length} pageSize={5} customResultsLabel="records" additionalText="(2 sides per record)" /> </Card.Section> </Card> ); }; ``` #### Accepted BrAT Variant Behaviors - ALL (JAWS, NVDA, VoiceOver) - Announce status update "X of Y" when changing pages - “X of Y” announced in normal reading order between [ < ] and [ > ] - JAWS - Correctly announces "list of 2 items" - Does not announce "X of Y" as part of `<nav>` on focus - NVDA, VoiceOver (Mac) - Incorrectly announces "list of 3 items" - Does announce "X of Y" as part of `<nav>` on focus </Tab> --- id: pie category: Data Visualization title: Pie slug: /web/ui/charts/pie description: A graphical representation of data in a circular-shaped graph. design: https://www.figma.com/design/NnKHAtlU3Q0Xq3RzN9PJe1/Abyss-Data-Visualization?node-id=3-22731 --- <Tab label="Overview"> Note: JPG and PNG download options are not compatible with Safari. As an alternative, please use the PDF option or take a screenshot. ```jsx import { Charts } from '@uhg-abyss/web/ui/Charts'; ``` ## Pie chart Simple Pie chart with two data sets having `title` and `subtitle` props passed. `xAxisLabel` and `yAxisLabel` are required props for chart. ```jsx live () => { const labels = ['Promoters', 'Passives', 'Detractors']; const data = { labels, datasets: [ { label: 'Score', data: [65, 59, 80], backgroundColor: [ '$primaryDvz1', Charts.pattern.draw('line', '$secondaryDvz1'), Charts.pattern.draw('diagonal', '$purpleDvz1'), ], borderColor: ['$primaryDvz1', '$secondaryDvz1', '$purpleDvz1'], }, ], }; return ( <div> <Charts.Pie data={data} title="Avg Nps Score" subtitle="Percentage by group type" xAxisLabel="Type" yAxisLabel="Score" /> </div> ); }; ``` ## Pie options Pass `cutout`, `rotation`, `circumference` values to options of the Pie chart to set the thickness of the arc, the start angle to draw the arc from, and the sweep to allow the arcs to cover. The default values are `0`, `0`, `360`, respectively. ```jsx live () => { const labels = ['Promoters', 'Passives', 'Detractors']; const data = { labels, datasets: [ { label: 'Pie Options', data: [65, 65, 65], backgroundColor: [ '$primaryDvz1', Charts.pattern.draw('line', '$secondaryDvz1'), Charts.pattern.draw('diagonal', '$purpleDvz1'), ], borderColor: ['$primaryDvz1', '$secondaryDvz1', '$purpleDvz1'], }, ], }; return ( <div> <Charts.Pie data={data} title="Pie Options" subtitle="Options for Pie chart specific" xAxisLabel="Type" yAxisLabel="Score" options={{ rotation: 270, circumference: 180, plugins: { datalabels: { display: false, }, }, }} /> </div> ); }; ``` ## Limitation Limiting the number of data points to 6. If the data set is larger than 6 items or the pie segments are small in size , we recommend using a different chart type for better readability, such as Bar Chart. ```jsx live () => { const labels = [ 'Promoters', 'Passives', 'Detractors', 'Buyers', 'Recruiters', 'Sellers', ]; const data = { labels, datasets: [ { label: 'Dataset', data: [65, 59, 80, 81, 56, 55], backgroundColor: [ '$primaryDvz1', Charts.pattern.draw('line', '$secondaryDvz1'), Charts.pattern.draw('diagonal', '$purpleDvz1'), Charts.pattern.draw('dot', '$tangerineDvz1'), Charts.pattern.draw('dash', '$sapphireDvz1'), Charts.pattern.draw('weave', '$gray6'), ], borderColor: [ '$primaryDvz1', '$secondaryDvz1', '$purpleDvz1', '$tangerineDvz1', '$sapphireDvz1', '$gray6', ], }, ], }; return ( <div> <Charts.Pie data={data} title="Limitation" subtitle="Limit the data points to 6" xAxisLabel="Type" yAxisLabel="Score" titleOffset={3} options={{ plugins: { datalabels: { display: false, }, }, }} /> </div> ); }; ``` ## Data structure Data in the datasets can be different structures and can be found in the <ExitLink href="https://www.chartjs.org/docs/latest/general/data-structures.html">Data Structures</ExitLink> docs. When using the Pie chart type, the parsing object should have a `key` item that points to the value to look at. In this example, the Pie chart will show two items with values 1500 and 500. ```jsx live () => { const labels = ['Sales', 'Purchases']; const data = { labels, datasets: [ { label: 'Dataset 1', data: [ { id: 'Sales', nested: { value: 1500 } }, { id: 'Purchases', nested: { value: 500 } }, ], backgroundColor: ['$primaryDvz1', '$secondaryDvz1'], borderColor: ['$primaryDvz1', '$secondaryDvz1'], }, ], }; return ( <div> <Charts.Pie data={data} title="Profile Views" subtitle="The feature shows you profile view statistics." xAxisLabel="Month" yAxisLabel="Views" options={{ parsing: { key: 'nested.value', }, }} /> </div> ); }; ``` ## Options Use `options` prop to customize the chart level and dataset level. Configuration for the options can be found in the <ExitLink href="https://www.chartjs.org/docs/4.4.7/charts/doughnut.html#config-options">Options</ExitLink> docs. ```jsx live () => { const labels = ['Promoters', 'Passives', 'Detractors']; const data = { labels, datasets: [ { label: 'Dataset 1', data: [65, 59, 80], backgroundColor: [ '$tangerineDvz1', Charts.pattern.draw('dot', '$sapphireDvz1'), Charts.pattern.draw('dash', '$statusDvz1'), ], borderColor: ['$tangerineDvz1', '$sapphireDvz1', '$statusDvz1'], datalabels: { labels: { index: { formatter: function (value, ctx) { const total = ctx.dataset.data.reduce( (previousValue, currentValue) => { return previousValue + currentValue; } ); const percentage = Math.floor((value / total) * 100 + 0.5); return [ctx.chart.data.labels[ctx.dataIndex], `${percentage}%`]; }, }, }, }, }, ], }; return ( <div> <Charts.Pie data={data} title="Options Config" subtitle="Options configuration for chart" xAxisLabel="Type" yAxisLabel="Score" options={{ plugins: { tooltip: { callbacks: { label(context) { const { dataset } = context; const pointValue = dataset.data[context.dataIndex]; const total = dataset.data.reduce( (previousValue, currentValue) => { return previousValue + currentValue; } ); const percentage = Math.floor( (pointValue / total) * 100 + 0.5 ); return `${dataset.label}: ${percentage}%`; }, }, }, }, }} /> </div> ); }; ``` ## Chart description Use `chartDescription` prop to describe the chart, which will be shown in the chart description accordion below the view data table accordion. The default value of `chartDescription` is `null`. Whether displayed or not, the chart description accordion, including its content, are announced as the “long description” for the chart. ```jsx live () => { const labels = ['Promoters', 'Passives', 'Detractors', 'Buyers']; const data = { labels, datasets: [ { label: 'NPS Visitors', data: [22, 65, 75, 85], backgroundColor: [ '$tangerineDvz1', Charts.pattern.draw('dash', '$sapphireDvz1'), Charts.pattern.draw('weave', '$redDvz1'), Charts.pattern.draw('line', '$statusDvz1'), ], borderColor: [ '$tangerineDvz1', '$sapphireDvz1', '$redDvz1', '$statusDvz1', ], }, ], }; return ( <div> <Charts.Pie data={data} title="Chart Description" subtitle="Describe the chart" xAxisLabel="Type" yAxisLabel="Score" chartDescription={ 'Pie chart plotted with Promoters,Passives,Detractors,Buyers and having more percentage of visitors for buyers group type' } options={{ plugins: { datalabels: { display: false, }, }, }} /> </div> ); }; ``` ## Chart type Use `chartType` prop to describe the type of Pie chart. The default value is `Pie Chart`. ```jsx live () => { const labels = ['Promoters', 'Passives']; const data = { labels, datasets: [ { label: 'Dataset 1', data: [65, 50], backgroundColor: [ '$primaryDvz1', Charts.pattern.draw('dot', '$secondaryDvz1'), ], borderColor: ['$primaryDvz1', '$secondaryDvz1'], }, ], }; return ( <div> <Charts.Pie data={data} title="Custom Pie" subtitle="Custom Pie chart" xAxisLabel="Type" yAxisLabel="Score" chartType="Custom Pie Chart" options={{ rotation: 90, circumference: 360, plugins: { datalabels: { display: false, }, }, }} /> </div> ); }; ``` ## Pattern pie chart Use `Charts.pattern` prop in dataset to make patterns in the Pie chart, which helps viewers with vision deficiencies. Refer to the <ExitLink href="https://github.com/ashiguruma/patternomaly">Patternomaly</ExitLink> library to generate patterns to fill datasets. ```jsx live () => { const labels = ['Promoters', 'Passives', 'Detractors', 'Buyers']; const data = { labels, datasets: [ { data: [45, 25, 20, 10], backgroundColor: [ Charts.pattern.draw('square', '$primaryDvz1'), Charts.pattern.draw('circle', '$secondaryDvz1'), Charts.pattern.draw('diamond', '$purpleDvz1'), Charts.pattern.draw('triangle', '$tangerineDvz1'), ], borderColor: [ Charts.pattern.draw('square', '$primaryDvz1'), Charts.pattern.draw('circle', '$secondaryDvz1'), Charts.pattern.draw('diamond', '$purpleDvz1'), Charts.pattern.draw('triangle', '$tangerineDvz1'), ], }, ], }; return ( <React.Fragment> <Charts.Pie data={data} title="Patterned Chart" subtitle="Pattern Pie Chart" xAxisLabel="Type" yAxisLabel="Score" titleOffset={3} chartType="Pattern Pie Chart" options={{ plugins: { datalabels: { display: false, }, }, }} /> </React.Fragment> ); }; ``` ## Title offset Use `titleOffset` prop to change the heading level of graph title in a page. The default value is `1`. You can use titleOffset={1|2|3|4|5}. ```jsx live () => { const labels = ['Promoters', 'Passives', 'Detractors']; const data = { labels, datasets: [ { label: 'Dataset', data: [65, 59, 80], backgroundColor: [ '$primaryDvz1', Charts.pattern.draw('line', '$secondaryDvz1'), Charts.pattern.draw('diagonal', '$purpleDvz1'), ], borderColor: ['$primaryDvz1', '$secondaryDvz1', '$purpleDvz1'], }, ], }; return ( <div> <Charts.Pie data={data} title="Title Offset" subtitle="Title heading level" xAxisLabel="Type" yAxisLabel="Score" titleOffset={3} /> </div> ); }; ``` ## Data labels Use `datalabels` plugins option to add custom labels to the Pie chart.`datalabels` can also be configured in dataset level, as shown below. More details for customizing datalabels can found here <ExitLink href="https://chartjs-plugin-datalabels.netlify.app/samples/advanced/multiple-labels.html">Datalabels</ExitLink> ```jsx live () => { const labels = ['Promoters', 'Passives', 'Detractors']; const data = { labels, datasets: [ { label: 'Dataset', data: [65, 59, 80], backgroundColor: [ '$primaryDvz1', Charts.pattern.draw('line', '$secondaryDvz1'), Charts.pattern.draw('diagonal', '$purpleDvz1'), ], borderColor: ['$primaryDvz1', '$secondaryDvz1', '$purpleDvz1'], datalabels: { labels: { index: { formatter: function (value, ctx) { const total = ctx.dataset.data.reduce( (previousValue, currentValue) => { return previousValue + currentValue; } ); const percentage = Math.floor((value / total) * 100 + 0.5); return [ctx.chart.data.labels[ctx.dataIndex], `${percentage}%`]; }, }, }, }, }, ], }; return ( <div> <Charts.Pie data={data} title="Data Labels" subtitle="Custom label chart" xAxisLabel="Type" yAxisLabel="Score" chartType="Custom Label Pie Chart" options={{ plugins: { tooltip: { callbacks: { label(context) { const { dataset } = context; const pointValue = dataset.data[context.dataIndex]; const total = dataset.data.reduce( (previousValue, currentValue) => { return previousValue + currentValue; } ); const percentage = Math.floor( (pointValue / total) * 100 + 0.5 ); return `${dataset.label}: ${percentage}%`; }, }, }, }, }} /> </div> ); }; ``` ## Hiding dropdowns Use the `hideDataTable` prop to remove the "View Data Table" accordion dropdown below the chart. Use the `hideDownloadDropdown` prop to remove the download options dropdown in the upper right corner of the chart. The default setting for both options is `false`. ```jsx live () => { const labels = ['Promoters', 'Passives', 'Detractors']; const data = { labels, datasets: [ { label: 'Score', data: [65, 59, 80], backgroundColor: [ '$primaryDvz1', Charts.pattern.draw('line', '$secondaryDvz1'), Charts.pattern.draw('diagonal', '$purpleDvz1'), ], borderColor: ['$primaryDvz1', '$secondaryDvz1', '$purpleDvz1'], }, ], }; return ( <div> <Charts.Pie data={data} title="Avg Nps Score" subtitle="Percentage by group type" xAxisLabel="Type" yAxisLabel="Score" hideDataTable hideDownloadDropdown /> </div> ); }; ``` ## Showing dropdowns Use the `openDataTable` prop to expand the "View Data Table" accordion dropdown below the chart by default. The default is `false`. Setting to `true` expands the accordion by default, while setting it to `'always'` prevents the accordion from being collapsible, and is thus always open. ```jsx live () => { const labels = ['Promoters', 'Passives', 'Detractors']; const data = { labels, datasets: [ { label: 'Score', data: [65, 59, 80], backgroundColor: [ '$primaryDvz1', Charts.pattern.draw('line', '$secondaryDvz1'), Charts.pattern.draw('diagonal', '$purpleDvz1'), ], borderColor: ['$primaryDvz1', '$secondaryDvz1', '$purpleDvz1'], }, ], }; return ( <div> <Charts.Pie data={data} title="Avg Nps Score" subtitle="Percentage by group type" xAxisLabel="Type" yAxisLabel="Score" openDataTable="always" /> </div> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={Charts.Pie} rows={[ { name: 'title', type: 'string', description: 'Title for the chart', }, { name: 'subtitle', type: 'string', description: 'Subtitle for the chart', }, { name: 'xAxisLabel', type: 'string', description: 'Label for the X-axis', }, { name: 'yAxisLabel', type: 'string', description: 'Label for the Y-axis', }, { name: 'data', type: 'object', description: 'Data input object for chart', }, { name: 'options', type: 'object', description: 'Custom chart options object', }, // { // name: 'enableZoom', // type: 'string', // description: 'Flag to toggle zooming for chart', // }, { name: 'chartDescription', type: 'string', description: 'Description of the chart', }, { name: 'titleOffset', type: 'number', description: 'Heading level of chart title', }, { name: 'chartType', type: 'string', description: 'Describes type of the chart', default: 'Pie Chart', }, { name: 'hideDataTable', type: 'bool', default: 'false', description: 'hides the "View Data Table" accordion dropdown', }, { name: 'hideDownloadDropdown', type: 'bool', default: 'false', description: 'hides the download options dropdown', }, { name: 'openDataTable', type: 'bool | "always"', default: 'false', description: 'opens the "View Data Table" accordion dropdown by default', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={'Chart'} rows={[ { name: 'chart-container', description: 'Chart container', }, { name: 'chart-canvas-wrapper', description: 'Chart canvas wrapper element', }, { name: 'chart-canvas-header-wrapper', description: 'Chart canvas header wrapper element', }, { name: 'chart-heading-container', description: 'Chart heading container', }, { name: 'chart-canvas-container', description: 'Chart canvas container', }, { name: 'chart-heading-wrapper', description: 'Chart heading wrapper', }, { name: 'chart-title', description: 'Chart title', }, { name: 'chart-subtitle', description: 'Chart subtitle', }, { name: 'chart-download-dropdown', description: 'Chart download options dropdown', }, { name: 'chart-canvas', description: 'Chart canvas element', }, { name: 'chart-canvas-music', description: 'Chart canvas keyboard navigation element', }, ]} /> ``` </Tab> <Tab label="Accessibility"> <h2>Chart accessibility requirements</h2> - Text contrast must be 4.5:1 or greater - Single chart bar color contrast must be 3:1 or greater - Pie segments must be more than a difference in color - For pie charts: use patterns <h2>Chart “long description”</h2> - Whether displayed or not, the chart description accordion, including its content, are announced as the “long description” for the chart. ```jsx live () => { const labels = ['Promoters', 'Passives', 'Detractors']; const data = { labels, datasets: [ { label: 'Score', data: [65, 59, 80], backgroundColor: [ '$primaryDvz1', Charts.pattern.draw('line', '$secondaryDvz1'), Charts.pattern.draw('diagonal', '$purpleDvz1'), ], borderColor: ['$primaryDvz1', '$secondaryDvz1', '$purpleDvz1'], }, ], }; return ( <div> <Charts.Pie data={data} title="Avg Nps Score" subtitle="Percentage by group type" xAxisLabel="Type" yAxisLabel="Score" /> </div> ); }; ``` <h3> Reduced Motion </h3> Animations and transitions that have been changed when a user has `prefers-reduced-motion` set to `reduced` for all Data Visualizations: - No inflation of bars, sections or lines upon initial data rendering - Data point tooltip navigation has animation removed - View Data Table Accordion has transitions removed ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Tab', description: 'Moves focus to the next focusable element; focuses the canvas chart', }, { name: 'Space', description: 'When focus is on the canvas, pressing Space will focus the first data point of the first dataset in the chart', }, { name: 'Arrow Right', description: 'Moves focus to the next data point', }, { name: 'Arrow Left', description: 'Moves focus to the previous data point', }, // { // name: 'Function + Arrow Down', // description: 'Focus shift to the next dataset in the chart', // }, // { // name: 'Function + Arrow Up', // description: 'Focus shift to the previous dataset in the chart', // }, { name: 'Home', description: 'Moves focus to first data point of current dataset', }, { name: 'End', description: 'Moves focus to last data point of current dataset', }, ]} /> ``` <h2>Known screen reader issues</h2> <h3>NVDA and JAWS</h3> Datapoint navigation announce tooltip content twice - The second time includes chart name </Tab> --- id: popover-v2 category: Overlay title: V2Popover description: Allows users to click an element to display a pop-up box. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=10565-18785 subDirectory: Popover/v2 sourceIsTS: true --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="Popover"></Docs.V2MigrationBanner> ``` ```jsx import { V2Popover } from '@uhg-abyss/web/ui/Popover'; ``` ```jsx sandbox { component: 'V2Popover', inputs: [ { prop: 'title', type: 'string', defaultValue: 'Concise and clear heading' }, { prop: 'content', type: 'ReactNode', defaultValue: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer vitae molestie risus, ut semper mi.' }, { prop: 'width', type: 'string', defaultValue: '343px' }, { prop: 'showClose', type: 'boolean', }, { prop: 'position', type: 'select', options: [ { label: 'left', value: 'left' }, { label: 'top', value: 'top' }, { label: 'right', value: 'right' }, { label: 'bottom', value: 'bottom' }, ], defaultValue: 'top' }, ], } <V2Popover> Click to open popover </V2Popover> ``` ## Default popover trigger If no children are passed to the `V2Popover` component, the default trigger will be the "help" IconSymbol. ```jsx live <V2Popover title="Concise and clear heading" content="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer vitae molestie risus, ut semper mi." /> ``` ## Heading The `title` prop accepts a `string` and is used to set the title of the popover, as well as aria labels. For further customization, you can use the `heading` prop to pass a `ReactNode`, which is not used for aria labeling. Even when using a custom heading, it is recommended to still set the `title` prop for accessibility purposes. To hide the close button in the heading, set the `showClose` prop to `false`. ```jsx live () => { const customHeading = ( <Layout.Group alignItems="left"> <IconSymbol icon="info" /> <span>Custom Heading</span> </Layout.Group> ); return ( <Layout.Group> <V2Popover title="Popover Title" content="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer vitae molestie risus, ut semper mi." > <V2Button>Show Popover with Title</V2Button> </V2Popover> <V2Popover showClose={false} title="Custom Heading" heading={customHeading} content="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer vitae molestie risus, ut semper mi." > <V2Button>Show Popover with Custom Heading</V2Button> </V2Popover> </Layout.Group> ); }; ``` ## Content The `content` prop accepts a `ReactNode`. This allows for the flexiblity to accomodate basic text as well as full custom UI layouts within body of the popover. ```jsx live () => { const popOverContent = ( <Layout.Stack alignItems="left"> <p> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer vitae molestie risus, ut semper mi. </p> <V2Button onClick={() => alert('Clicked inside popover!')}> Click Me </V2Button> </Layout.Stack> ); return ( <Layout.Group> <V2Popover title="Concise and clear heading" content="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer vitae molestie risus, ut semper mi." > <V2Button>Show String Content</V2Button> </V2Popover> <V2Popover title="Custom popover content" content={popOverContent} align="start" > <V2Button>Show React Node Content</V2Button> </V2Popover> </Layout.Group> ); }; ``` ## Custom popover trigger To utilize a custom trigger element, wrap with the `V2Popover` component with the custom element to replace the default and trigger the opening of the popover. ```jsx live <V2Popover title="Concise and clear heading" content="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer vitae molestie risus, ut semper mi." > <IconBrand icon="alert" size={40} /> </V2Popover> ``` ## Position Use the `position` prop to change the position of the Popover relative to its target. The valid options are `'top'`, `'right'`, `'bottom'`, and `'left'`. The default value is `'top'`. Note: The Popover will automatically reposition itself to stay within the viewport. This may result in the Popover not appearing on the side defined by the `position` prop and/or not being center-aligned with the target element. Additionally, the use of `'right'` and `'left'` on mobile screens is highly discouraged; prefer using `'top'` and `'bottom'` instead. The example below shows one method of achieving this. ```jsx live () => { const mobileBreakpoint = useToken('sizes')('$core.size.md'); const isMobile = useMediaQuery(`(max-width: ${mobileBreakpoint})`); return ( <Layout.Group space={20}> <V2Popover title="Top" content="Position Top" position="top"> Top </V2Popover> <V2Popover title="Right" content="Position Right" position={isMobile ? 'top' : 'right'} > Right </V2Popover> <V2Popover title="Bottom" content="Position Bottom" position="bottom"> Bottom </V2Popover> <V2Popover title="Left" content="Position Left" position={isMobile ? 'bottom' : 'left'} > Left </V2Popover> </Layout.Group> ); }; ``` ## Controlled open state Use a combination of the `onOpenChange` and `open` props to use a controlled state for opening and closing the popover. ```jsx live () => { const [isOpen, setIsOpen] = useState(false); const handleOpenChange = (open) => { // Only allows you to close the popover by clicking the V2Button if (open) { setIsOpen(true); } }; return ( <Layout.Stack alignItems="left" space={20}> <V2Popover title="Concise and clear heading" content="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer vitae molestie risus, ut semper mi." open={isOpen} hideClose onKeyDown={(e) => { // Allows you to close the popover by pressing the Escape key if (e.key === 'Escape') { setIsOpen(false); } }} onOpenChange={handleOpenChange} > Controlled Open State </V2Popover> <V2Button onClick={() => setIsOpen(!isOpen)}> {isOpen ? 'Close Popover' : 'Open Popover'} </V2Button> </Layout.Stack> ); }; ``` ## When should I use a tooltip vs a popover? Glad you asked! There are several considerations when deciding between a [Tooltip](/web/ui/tooltip-v2) or a [Popover](/web/ui/popover-v2): ### Purpose of content - A [Tooltip](/web/ui/tooltip-v2) is a hint or a tip about what an interactive element does. Tooltips are meant to help clarify or provide supplementary instruction for an element on hover or upon receiving focus. They should not be used to add additional content nor should they include interactive elements such as links. Tooltips should not receive mouse or keyboard focus. Try to position tooltips so they do not overlap and cover other content on the screen. This helps keep all content readable by all users and reduces concerns regarding <ExitLink href="https://www.w3.org/WAI/WCAG21/Understanding/content-on-hover-or-focus.html">WCAG 2.1 SC 1.4.13: Content on Hover or Focus</ExitLink> - A [Popover](/web/ui/popover-v2) should be used to provide additional content to static text, such as definitions of words, informational blurbs, or additional product details. They can receive focus and can contain links and other interactive elements. ### Size of content - Since [Tooltips](/web/ui/tooltip-v2) are only meant to tell the purpose of an element they should be short and to the point, for example: "Click X to do X" or "User post count". - [Popovers](/web/ui/popover-v2), on the other hand, can be much more verbose, they can include a heading, lines of text in the body, links, etc. ### Interactions - [Tooltips](/web/ui/tooltip-v2) should only be visible on mouse hover or upon receiving focus. For this reason, if you need to be able to read the content while interacting with other parts of the page then a [Tooltip](/web/ui/tooltip-v2) will not work. They should be dismissible using the "escape" key. They should be used on interactive elements where a mouse click or keyboard activation would otherwise trigger the elements primary function. - [Popovers](/web/ui/popover-v2) must be triggered to appear, whether via mouse click or via keyboard navigation. They must be dismissible, whether by clicking on other parts of the page, clicking the [Popover](/web/ui/popover-v2) target, or a specific close button/icon (depending on implementation). For this reason, you can set up a [Popover](/web/ui/popover-v2) to allow you to interact with other elements on the page while still being able to read its content. On top of this, since [Popovers](/web/ui/popover-v2) will remain open when mousing out of their target, you can add additional buttons or interactions within them. ### Conclusion If you want to give a short hint or supplemental instructions for an interactive element (such as a submit button), use a [Tooltip](/web/ui/tooltip-v2). If you want to add additional content to a static element that might include headings, body text, links, etc, and you need the content to remain open even after mousing away or the element losing focus, then use a [Popover](/web/ui/popover-v2). It should be noted that any vital information users need to complete an action or make a decision should be displayed directly in the page text or button label, rather than a [Tooltip](/web/ui/tooltip-v2) or a [Popover](/web/ui/popover-v2). Critical information hidden in a [Tooltip](/web/ui/tooltip-v2) or a [Popover](/web/ui/popover-v2) might not be discovered by all users and could create accessibility issues. </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2Popover" propTypeName="V2PopoverProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2ClassesTable title="V2Popover" classes={[PopoverClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> ```jsx live <Layout.Group space={40}> <V2Popover title="Top" content="This content is shown above button" position="top" > <V2Button aria-label="Up arrow" icon={{ icon: 'arrow_upward', position: 'icon-only' }} /> </V2Popover> <V2Popover title="Right" content="This content is next to the right side of button" position="right" > <V2Button aria-label="Right arrow" icon={{ icon: 'arrow_right_alt', position: 'icon-only' }} /> </V2Popover> <V2Popover title="Bottom" content="This content is displayed below button" position="bottom" > <V2Button aria-label="Down arrow" icon={{ icon: 'arrow_downward', position: 'icon-only' }} /> </V2Popover> <V2Popover title="Left" content="This content appears to the left of button" position="left" > <V2Button aria-label="Left arrow" icon={{ icon: 'arrow_left_alt', position: 'icon-only' }} /> </V2Popover> <V2Popover title="No content here!" position="left"> <V2Button aria-label="Left arrow" icon={{ icon: 'question_mark', position: 'icon-only' }} /> </V2Popover> <V2Popover content="Look, Ma! I have no title and do not meet all accessibility guidelines." position="left" > <V2Button aria-label="Left arrow" icon={{ icon: 'question_mark', position: 'icon-only' }} /> </V2Popover> </Layout.Group> ``` ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Esc', description: 'Close Popover', }, { name: 'Space', description: 'Close Popover when close button is present', }, ]} /> ``` </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={V2Popover} keys={['popoverV2']} /> ``` </Tab> --- id: popover category: Overlay title: Popover description: Allows users to click an element to display a pop-up box. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=0-1571 subDirectory: Popover/v1 --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="Popover"></Docs.V2MigrationBanner> ``` ```jsx import { Popover } from '@uhg-abyss/web/ui/Popover'; ``` ```jsx sandbox { component: 'Popover', inputs: [ { prop: 'content', type: 'ReactNode', }, { prop: 'title', type: 'string', }, { prop: 'width', type: 'string', }, { prop: 'positionOffset', type: 'number', }, { prop: 'position', type: 'select', options: [ { label: 'left', value: 'left' }, { label: 'top', value: 'top' }, { label: 'right', value: 'right' }, { label: 'bottom', value: 'bottom' }, ], }, { prop: 'hideArrow', type: 'boolean', }, { prop: 'showClose', type: 'boolean', }, ], } <Popover title="Concise and clear heading" content="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer vitae molestie risus, ut semper mi"> Click to open popover </Popover> ``` ## Default popover trigger If no children are passed to the `Popover` component, the default trigger will be the "info" IconSymbol. ```jsx live <Popover title="Concise and clear heading" content="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer vitae molestie risus, ut semper mi." /> ``` ## Title The `title` prop accepts a `string` and is used to set the title of the popover. ## Content The `content` prop accepts a `ReactNode`. This allows for the flexiblity to accomodate basic text as well as full custom UI layouts within body of the popover. ```jsx live () => { const popOverContent = ( <Layout.Stack alignItems="left"> <p> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer vitae molestie risus, ut semper mi. </p> <Button onClick={() => alert('Clicked inside popover!')}>Click Me</Button> </Layout.Stack> ); return ( <Layout.Group> <Popover title="Concise and clear heading" content="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer vitae molestie risus, ut semper mi." align="start" hasCustomButtonTrigger > <Button>Show String Content</Button> </Popover> <Popover content={popOverContent} align="start" hasCustomButtonTrigger> <Button>Show React Node Content</Button> </Popover> </Layout.Group> ); }; ``` ## Custom popover trigger To utilize a custom trigger element, wrap with the `Popover` component with the custom element to replace the default and trigger the opening of the popover. A11y Note: Whenever using a button element as a custom trigger, the `hasCustomButtonTrigger` prop must be set to `true` to avoid validateDOMNesting errors. ```jsx live <Layout.Group space={40}> <Popover title="Concise and clear heading" content="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer vitae molestie risus, ut semper mi." > <IconBrand icon="alert" size={40} /> </Popover> <Popover title="Concise and clear heading" content="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer vitae molestie risus, ut semper mi." hasCustomButtonTrigger > <Button>Custom Button Trigger</Button> </Popover> </Layout.Group> ``` ## Close button Use the `showClose` prop to add a close button option to the popover. For accessibility purposes, using a close button is recommended. ```jsx live <Layout.Group space={20}> <Popover title="Close button is displayed" content="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer vitae molestie risus, ut semper mi." showClose={true} > Show Close Button </Popover> <Popover title="Close button is hidden" content="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer vitae molestie risus, ut semper mi." showClose={false} > Hide Close Button </Popover> </Layout.Group> ``` ## Position Use the `position` prop to change the position of the popover. Options include `'left'` | `'right'` | `'top'` | `'bottom'`. ```jsx live <Layout.Group space={20}> <Popover title="Left" content="Position Left" position="left"> Left </Popover> <Popover title="Top" content="Position Top" position="top"> Top </Popover> <Popover title="Bottom" content="Position Bottom" position="bottom"> Bottom </Popover> <Popover title="Right" content="Position Right" position="right"> Right </Popover> </Layout.Group> ``` ## Position offset Use the `positionOffset` prop to change the horizontal offset position of the popover. ```jsx live <Layout.Group space={20}> <Popover title="Default Offset (8)">Default Position Offset</Popover> <Popover title="Offset of 16" positionOffset={16}> Offset of 16 </Popover> <Popover title="Offset of 32" positionOffset={32}> Offset of 32 </Popover> </Layout.Group> ``` ## Align Use the `align` prop to set the side of the anchor to render against when open. Options include `'start'`, `'center'`, and `'end'`. ```jsx live <Layout.Group space={20}> <Popover title="Start" content="Position Start" align="start"> Start </Popover> <Popover title="Center" content="Position Center" align="center"> Center </Popover> <Popover title="End" content="Position End" align="end"> End </Popover> </Layout.Group> ``` ## Align offset Use the `alignOffset` prop to change the offset position of the popover. ```jsx live <Layout.Group space={20}> <Popover title="Default Offset (8)" align="start"> Default Align Offset </Popover> <Popover title="Offset of 32" align="start" alignOffset={32}> Offset of 32 </Popover> </Layout.Group> ``` ## Show/hide arrow Use the `hideArrow` prop to hide an arrow element rendered alongside the popover. The default is set to `false`. This can be used to help visually link the popover with the content. ```jsx live <Layout.Group space={20}> <Popover title="Hide Arrow" hideArrow positionOffset={8} hasCustomButtonTrigger > <Button>Hide Arrow</Button> </Popover> <Popover title="Show Arrow" hasCustomButtonTrigger> <Button>Show Arrow</Button> </Popover> </Layout.Group> ``` ## Controlled open state Use a combination of the `onOpenChange` and `open` props to use a controlled state for opening and closing the popover. ```jsx live () => { const [isOpen, setIsOpen] = useState(false); return ( <Layout.Stack alignItems="left" space={20}> <Popover title="Concise and clear heading" content="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer vitae molestie risus, ut semper mi." open={isOpen} onOpenChange={() => { setIsOpen(!isOpen); }} > Controlled Open State </Popover> <Button onClick={() => setIsOpen(false)}> Programmatically Close Popover </Button> </Layout.Stack> ); }; ``` ## When should I use a tooltip vs a popover? Glad you asked! There are several considerations when deciding between a [Tooltip](/web/ui/tooltip) or a [Popover](/web/ui/popover): ### Purpose of content - A [Tooltip](/web/ui/tooltip) is a hint or a tip about what an interactive element does. Tooltips are meant to help clarify or provide supplementary instruction for an element on hover or upon receiving focus. They should not be used to add additional content nor should they include interactive elements such as links. Tooltips should not receive mouse or keyboard focus. Try to position tooltips so they do not overlap and cover other content on the screen. This helps keep all content readable by all users and reduces concerns regarding <ExitLink href="https://www.w3.org/WAI/WCAG21/Understanding/content-on-hover-or-focus.html">WCAG 2.1 SC 1.4.13: Content on Hover or Focus</ExitLink> - A [Popover](/web/ui/popover) should be used to provide additional content to static text, such as definitions of words, informational blurbs, or additional product details. They can receive focus and can contain links and other interactive elements. ### Size of content - Since [Tooltips](/web/ui/tooltip) are only meant to tell the purpose of an element they should be short and to the point, for example: "Click X to do X" or "User post count". - [Popovers](/web/ui/popover), on the other hand, can be much more verbose, they can include a heading, lines of text in the body, links, etc. ### Interactions - [Tooltips](/web/ui/tooltip) should only be visible on mouse hover or upon receiving focus. For this reason, if you need to be able to read the content while interacting with other parts of the page then a [Tooltip](/web/ui/tooltip) will not work. They should be dismissible using the "escape" key. They should be used on interactive elements where a mouse click or keyboard activation would otherwise trigger the elements primary function. - [Popovers](/web/ui/popover) must be triggered to appear, whether via mouse click or via keyboard navigation. They must be dismissible, whether by clicking on other parts of the page, clicking the [Popover](/web/ui/popover) target, or a specific close button/icon (depending on implementation). For this reason, you can set up a [Popover](/web/ui/popover) to allow you to interact with other elements on the page while still being able to read its content. On top of this, since [Popovers](/web/ui/popover) will remain open when mousing out of their target, you can add additional buttons or interactions within them. ### Conclusion If you want to give a short hint or supplemental instructions for an interactive element (such as a submit button), use a [Tooltip](/web/ui/tooltip). If you want to add additional content to a static element that might include headings, body text, links, etc, and you need the content to remain open even after mousing away or the element losing focus, then use a [Popover](/web/ui/popover). It should be noted that any vital information users need to complete an action or make a decision should be displayed directly in the page text or button label, rather than a [Tooltip](/web/ui/tooltip) or a [Popover](/web/ui/popover). Critical information hidden in a [Tooltip](/web/ui/tooltip) or a [Popover](/web/ui/popover) might not be discovered by all users and could create accessibility issues. </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={Popover} rows={[ { name: 'content', type: 'ReactNode', description: 'Content displayed in popover', }, { name: 'title', type: 'string', description: 'Set the title of the popover', }, { name: 'children', type: 'ReactNode', description: 'The element the popover wraps', }, { name: 'position', type: "'left' | 'right' | 'top' | 'bottom'", description: 'Set the direction where the popover displays', }, { name: 'align', type: "'start' | 'center' | 'end'", description: 'The side of the anchor to render against when open', }, { name: 'positionOffset', type: 'number', description: 'Set the position offset of where the popover displays', }, { name: 'alignOffset', type: 'number', description: 'Set the align offset of where the popover displays', }, { name: 'width', type: 'string | number', description: 'Width of the popover container', }, { name: 'showClose', type: 'boolean', description: 'Flag to show close button or not', }, { name: 'open', type: 'boolean', description: 'Flag to set open state of popover; must be used in conjunction with onOpenChange', }, { name: 'onOpenChange', type: 'function', description: 'Callback fired whenever the open state of popover changes', }, { name: 'hideArrow', type: 'boolean', description: 'Flag to show/hide arrow rendered alongside popover', }, { name: 'hasCustomButtonTrigger', type: 'boolean', description: 'Utilize whenever Popover is wrapping a custom trigger that is a button element, to avoid validateDOMNesting errors', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Popover} rows={[ { name: 'popover-root', description: 'Root', }, { name: 'popover-portal', description: 'Portal', }, { name: 'popover-trigger', description: 'Trigger', }, { name: 'popover-trigger-button', description: 'Trigger Button', }, { name: 'popover-trigger-icon', description: 'Trigger Icon', }, { name: 'popover-content', description: 'Content', }, { name: 'popover-header', description: 'Header', }, { name: 'popover-title', description: 'Header Title', }, { name: 'popover-close-button', description: 'Close Button', }, { name: 'popover-close-icon', description: 'Close Button Icon', }, { name: 'popover-content-container', description: 'Content Container', }, { name: 'popover-arrow', description: 'Arrow', }, ]} /> ``` </Tab> <Tab label="Accessibility"> ```jsx live <Layout.Group space={40}> <Popover title="Top" content="This content is shown above button" position="top" hasCustomButtonTrigger > <Button aria-label="Up arrow" rounded> <IconSymbol icon="arrow_upward" /> </Button> </Popover> <Popover title="Right" content="This content is next to the right side of button" position="right" hasCustomButtonTrigger > <Button aria-label="Right arrow" rounded> <IconSymbol icon="arrow_right_alt" /> </Button> </Popover> <Popover title="Bottom" content="This content is displayed below button" position="bottom" hasCustomButtonTrigger > <Button aria-label="Down arrow" rounded> <IconSymbol icon="arrow_downward" /> </Button> </Popover> <Popover title="Left" content="This content appears to the left of button" position="left" hasCustomButtonTrigger > <Button aria-label="Left arrow" rounded> <IconSymbol icon="arrow_left_alt" /> </Button> </Popover> <Popover title="No content here!" position="left" hasCustomButtonTrigger> <Button aria-label="Left arrow" rounded> <IconSymbol icon="question_mark" /> </Button> </Popover> <Popover content="Look, Ma! I have no title and do not meet all accessibility guidelines." position="left" hasCustomButtonTrigger > <Button aria-label="Left arrow" rounded> <IconSymbol icon="question_mark" /> </Button> </Popover> </Layout.Group> ``` ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Esc', description: 'Close Popover', }, { name: 'Space', description: 'Close Popover when close button is present', }, ]} /> ``` </Tab> --- id: print-provider category: Providers title: PrintProvider description: Allows print functionality. --- <Tab label="Overview"> ```jsx import { PrintProvider } from '@uhg-abyss/web/ui/PrintProvider'; ``` ```jsx render <Docs.V2Deprecated componentName="PrintProvider" /> ``` ## Usage Applications must be wrapped in the `PrintProvider` in order to manage the print view for your application. ```jsx <PrintProvider> <AppRoot /> </PrintProvider> ``` ## usePrint Through usage of the `usePrint` hook you can either trigger the native browser print capability, or activate a PDF download. Refer to [usePrint](../hooks/use-print) for more details. ```jsx import { usePrint } from '@uhg-abyss/web/hooks/usePrint'; ``` ```jsx live () => { const print = usePrint(); const logPrint = () => { console.log('print complete'); }; const logPDF = (pdf) => { console.log('pdf', pdf); }; return ( <React.Fragment> <Layout.Group> <Button onClick={() => print.printPage(logPrint, { openNewWindow: true })} > Print Page </Button> <Button onClick={() => print.savePDF(logPDF)}>Save PDF</Button> <Button onClick={() => print.createPDF(logPDF)}>Create PDF</Button> </Layout.Group> <Layout.Space /> <Box align="start"> <Text color="$primary1" fontWeight="$bold"> Hello World </Text> </Box> <Print.Section> <Print.Value>Hello World</Print.Value> </Print.Section> </React.Fragment> ); }; ``` ## Print elements Using the Print Elements, we are able to customize how our content appears when printed/saved as a PDF. ### Print.Section Use `Print.Section` to section out content in the print area. ```jsx live () => { const print = usePrint(); const logPDF = (pdf) => { console.log('pdf', pdf); }; return ( <React.Fragment> <Layout.Group> <Button onClick={() => print.printPage()}>Print Page</Button> <Button onClick={() => print.savePDF(logPDF)}>Save PDF</Button> <Button onClick={() => print.createPDF(logPDF)}>Create PDF</Button> </Layout.Group> <Layout.Space /> <Box align="start"> <Text color="$primary1" fontWeight="$bold"> Hello World </Text> </Box> <Print.Section> <Print.Value>Hello World (Print Section)</Print.Value> </Print.Section> </React.Fragment> ); }; ``` ### Print.Title Use `Print.Title` to put a title in your printable section. ```jsx live () => { const print = usePrint(); const logPDF = (pdf) => { console.log('pdf', pdf); }; return ( <React.Fragment> <Layout.Group> <Button onClick={() => print.printPage()}>Print Page</Button> <Button onClick={() => print.savePDF(logPDF)}>Save PDF</Button> <Button onClick={() => print.createPDF(logPDF)}>Create PDF</Button> </Layout.Group> <Layout.Space /> <Box align="start"> <Heading offset={1} color="$primary1" fontWeight="$bold"> Hello World </Heading> </Box> <Print.Section> <Print.Title>Hello World (Print Title)</Print.Title> </Print.Section> </React.Fragment> ); }; ``` ### Print.Label Use `Print.Label` to put a label in your printable section. ```jsx live () => { const print = usePrint(); const logPDF = (pdf) => { console.log('pdf', pdf); }; return ( <React.Fragment> <Layout.Group> <Button onClick={() => print.printPage()}>Print Page</Button> <Button onClick={() => print.savePDF(logPDF)}>Save PDF</Button> <Button onClick={() => print.createPDF(logPDF)}>Create PDF</Button> </Layout.Group> <Layout.Space /> <Box align="start"> <Label>Hello World: </Label> </Box> <Print.Section> <Print.Label>Hello World: (Print Label)</Print.Label> </Print.Section> </React.Fragment> ); }; ``` ### Print.Value Use `Print.Value` to put a normal text element in your printable section. ```jsx live () => { const print = usePrint(); const logPDF = (pdf) => { console.log('pdf', pdf); }; return ( <React.Fragment> <Layout.Group> <Button onClick={() => print.printPage()}>Print Page</Button> <Button onClick={() => print.savePDF(logPDF)}>Save PDF</Button> <Button onClick={() => print.createPDF(logPDF)}>Create PDF</Button> </Layout.Group> <Layout.Space /> <Box align="start"> <Text color="$primary1" fontWeight="$bold"> Hello World </Text> </Box> <Print.Section> <Print.Value>Hello World (Print Value)</Print.Value> </Print.Section> </React.Fragment> ); }; ``` ### Print.Table Use `Print.Table` to put a table in your printable section. `columns` should be objects that have a name and value and `data` should be the row values. ```jsx live () => { const print = usePrint(); const logPDF = (pdf) => { console.log('pdf', pdf); }; const columns = [ { name: 'Name', key: 'name' }, { name: 'Type', key: 'type' }, { name: 'Date Modified', key: 'date' }, ]; const rows = [ { id: 1, name: 'Games', date: '6/7/2020', type: 'File folder' }, { id: 2, name: 'Program Files', date: '4/7/2021', type: 'File folder' }, { id: 3, name: 'bootmgr', date: '11/20/2010', type: 'System file' }, { id: 4, name: 'log.txt', date: '1/18/2016', type: 'Text Document' }, ]; const printCols = [ { name: 'Name', value: '{{name}}' }, { name: 'Type', value: '{{type}}' }, { name: 'Date Modified', value: '{{date}}' }, ]; return ( <React.Fragment> <Layout.Group> <Button onClick={() => print.printPage()}>Print Page</Button> <Button onClick={() => print.savePDF(logPDF)}>Save PDF</Button> <Button onClick={() => print.createPDF(logPDF)}>Create PDF</Button> </Layout.Group> <Layout.Space /> <Box align="start"> <Table title="Base Static Table" columns={columns} rows={rows} /> </Box> <Print.Section> <Print.Table data={rows} columns={printCols} /> </Print.Section> </React.Fragment> ); }; ``` ### Print.Image Use `Print.Image` to put an image in your printable section. ```jsx live () => { const print = usePrint(); const img = utils.useBaseUrl(`img/logo.svg`); const logPDF = (pdf) => { console.log('pdf', pdf); }; return ( <React.Fragment> <Layout.Group> <Button onClick={() => print.printPage()}>Print Page</Button> <Button onClick={() => print.savePDF(logPDF)}>Save PDF</Button> <Button onClick={() => print.createPDF(logPDF)}>Create PDF</Button> </Layout.Group> <Layout.Space /> <Box align="start"> <img src={img} alt="abyss.png" /> </Box> <Print.Section> <Print.Image>{img}</Print.Image> </Print.Section> </React.Fragment> ); }; ``` ### Print.ListItem Use `Print.ListItem` to put a list into your printable section. ```jsx live () => { const print = usePrint(); const logPDF = (pdf) => { console.log('pdf', pdf); }; return ( <React.Fragment> <Layout.Group> <Button onClick={() => print.printPage()}>Print Page</Button> <Button onClick={() => print.savePDF(logPDF)}>Save PDF</Button> <Button onClick={() => print.createPDF(logPDF)}>Create PDF</Button> </Layout.Group> <Layout.Space /> <Box align="start"> <ul> <li>Alpha</li> <li>Beta</li> <li>Charlie</li> </ul> </Box> <Print.Section> <Print.ListItem>Alpha</Print.ListItem> <Print.ListItem>Beta</Print.ListItem> <Print.ListItem>Charlie</Print.ListItem> </Print.Section> </React.Fragment> ); }; ``` ### Print.Box Use `Print.Box` to create a box around content you want to print ```jsx live () => { const print = usePrint(); const logPDF = (pdf) => { console.log('pdf', pdf); }; return ( <React.Fragment> <Layout.Group> <Button onClick={() => print.printPage()}>Print Page</Button> <Button onClick={() => print.savePDF(logPDF)}>Save PDF</Button> <Button onClick={() => print.createPDF(logPDF)}>Create PDF</Button> </Layout.Group> <Layout.Space /> <Box align="start"> <Text color="$primary1" fontWeight="$bold"> Hello World </Text> </Box> <Print.Section> <Print.Box>Hello World (Print Box)</Print.Box> </Print.Section> </React.Fragment> ); }; ``` </Tab> <Tab label='Integration'> ```jsx render <Docs.PropsTable of={PrintProvider} rows={[ { name: 'children', type: 'ReactNode', description: 'Application contents', }, ]} /> ``` ```jsx render <Docs.PropsTable of={Print.Section} rows={[ { name: 'children', type: 'ReactNode', description: 'The contents of the Section component', }, { name: 'showPrint', type: 'boolean', description: 'decides if section shows up in the print or not', }, { name: 'hideBorder', type: 'boolean', description: 'decides if border is shown or not', }, ]} /> ``` ```jsx render <Docs.PropsTable of={Print.Title} rows={[ { name: 'children', type: 'ReactNode', description: 'The contents of the Title component', }, ]} /> ``` ```jsx render <Docs.PropsTable of={Print.Label} rows={[ { name: 'children', type: 'ReactNode', description: 'The contents of the Label component', }, ]} /> ``` ```jsx render <Docs.PropsTable of={Print.Value} rows={[ { name: 'children', type: 'ReactNode', description: 'The contents of the Value component', }, ]} /> ``` ```jsx render <Docs.PropsTable of={Print.Table} rows={[ { name: 'columns', type: 'array[object]', description: 'Array of column data. { name: string, value: valueKey }', }, { name: 'data', type: 'array[object]', description: 'Array of row data. { id: number, valueKey: string }', }, ]} /> ``` ```jsx render <Docs.PropsTable of={Print.Image} rows={[ { name: 'children', type: 'ReactNode', description: 'The contents of the Image component', }, ]} /> ``` ```jsx render <Docs.PropsTable of={Print.ListItem} rows={[ { name: 'children', type: 'ReactNode', description: 'The contents of the ListItem component', }, ]} /> ``` ```jsx render <Docs.PropsTable of={Print.Box} rows={[ { name: 'children', type: 'ReactNode', description: 'The contents of the Box component', }, ]} /> ``` </Tab> --- id: progress-bar-v2 category: Feedback title: V2ProgressBar description: Used to show users the status of loading an app, ongoing processes, saving changes/updates, and more. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=12558-42586 subDirectory: ProgressBar/v2 sourceIsTS: true --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="ProgressBar"></Docs.V2MigrationBanner> ``` ```jsx import { V2ProgressBar } from '@uhg-abyss/web/ui/ProgressBar'; ``` ```jsx sandbox { component: 'V2ProgressBar', inputs: [ { prop: 'label', type: 'string', }, { prop: 'subText', type: 'string', }, { prop: 'fillColor', type: 'string', }, { prop: 'width', type: 'string', }, { prop: 'duration', type: 'number', }, { prop: 'percentage', type: 'number', }, { prop: 'progressLabel', type: 'string', }, { prop: 'showProgress', type: 'boolean', }, { prop: 'hideLabel', type: 'boolean', }, { prop: 'showEndpoint', type: 'boolean', }, { prop: 'isIndeterminate', type: 'boolean', }, ] } <V2ProgressBar percentage={25} duration={5000}/> ``` ## Labels Use the `label` and `subText` props to provide information above the progress bar. A `label` is required for accessibility reasons. Use the `hideLabel` prop to visually hide the label. See the [Accessibility tab](/web/ui/progress-bar?tab=accessibility) for more information. ```jsx live <V2ProgressBar label="Label" subText="subtext" /> ``` ### Heading level For better screen reader support, the label element is treated as a heading (`h3`). Use the `headingLevel` prop to manually to set the heading level of the label. The default is set to `3` which renders the heading element as an `<h3>` See the [Accessibility tab](/web/ui/progress-bar-v2?tab=accessibility) for more information. ```jsx live <V2ProgressBar label="Label" headingLevel={1} percentage={30} /> ``` ### Show progress and progress label Use the `showProgress` prop to display the percentage number at the end of the filled progress bar space. If `showProgress` is true, the label shown defaults to the percentage the progress bar is filled. Use the `progressLabel` prop to provide a custom label in place of this. Doing so is strongly recommended if the progress bar is used to display any value that is not a percentage. ```jsx live <Layout.Stack grow space={20}> <V2ProgressBar label="Percentage Progress" percentage={30} showProgress /> <V2ProgressBar label="Progress Label" percentage={30} showProgress progressLabel="Loading..." /> </Layout.Stack> ``` ### Popover Use the `popover` prop to display a popover icon next to the label. This is useful for providing additional context or information about the progress bar. The `popover` prop accepts an object with the following properties: - `title`: The title of the popover. - `content`: The content of the popover. ```jsx live <V2ProgressBar label="Label" popover={{ title: 'Popover Title', content: 'This is the content of the popover', }} /> ``` ### Visually hidden labels Use `hideLabel` to visually hide the label. Note: You are still required to provide a `label` to meet accessibility standards. This label will be visually hidden but still read by screen readers. ```jsx live <V2ProgressBar percentage={25} label="visually hidden label" hideLabel /> ``` ### Validation Use the `validation` prop to display a validation message below the progress bar. This is useful for providing feedback to the user about the progress bar's state. The `validation` prop accepts an object with the following properties: - `type`: The type of validation message. This can be one of the following: `'success'` or `'error'`. - `message`: The validation message to display (optional). - `hideMessage`: If set to `true`, the message will not be displayed, but the validation icon will still be shown. This visually hides the message, but it will still be read by screen readers. Note: The `validation` prop will override the `showProgress` prop with an icon representing the validation type. ```jsx live <Layout.Stack grow space={20}> <V2ProgressBar label="Success" percentage={100} progressLabel={'Loading...'} validation={{ type: 'success', message: 'Complete!' }} /> <V2ProgressBar label="Error" percentage={100} progressLabel={'Loading...'} validation={{ type: 'error', message: 'Error!' }} /> <V2ProgressBar label="Success" percentage={100} progressLabel={'Loading...'} validation={{ type: 'success', message: 'Profile load completed!', hideMessage: true, }} /> </Layout.Stack> ``` ## Width Use the `width` prop to set the width of the progress bar. The default width is set to `100%`. This can be set to any valid CSS width value, such as `250px`, `300`, `75%`, or `50vw`. ```jsx live <Layout.Stack grow space={20}> <V2ProgressBar label="250px" percentage={25} width="250px" /> <V2ProgressBar label="300" percentage={25} width={300} /> <V2ProgressBar label="75%" percentage={25} width="75%" /> <V2ProgressBar label="50vw" percentage={25} width="50vw" /> </Layout.Stack> ``` ## Color Use the `fillColor` prop to change the color of the progress bar fill. On this prop you can pass any six-digit hex color code, or a color token from the [Color Tokens](/web/brand/uhc/tokens) page. Note: the background is always at 20% opacity to meet the contrast ratio of 3:1 with the background color. ```jsx live <Layout.Stack grow space={20}> <V2ProgressBar label="#371F76" percentage={25} fillColor="#371F76" /> <V2ProgressBar label="$core.color.turquoise.80" percentage={25} fillColor="$core.color.turquoise.80" /> </Layout.Stack> ``` ## Show endpoint Use the `showEndpoint` prop to display a small colored tip at the end of the progress bar. This helps indicate the end of the bar. ```jsx live <Layout.Stack grow space={20}> <V2ProgressBar label="showEndpoint" percentage={50} showEndpoint /> </Layout.Stack> ``` ## Duration Use the `duration` prop to set the time it takes in milliseconds for the fill bar to reach the set percentage. The default is set to `0`. ```jsx live <Layout.Stack grow space={20}> <V2ProgressBar label="5000ms" percentage={50} duration={5000} /> <V2ProgressBar label="10000ms" percentage={50} duration={10000} /> </Layout.Stack> ``` ## Indeterminate Use the `isIndeterminate` prop to set the progress bar to an indeterminate state. This is useful when the progress bar is used to indicate that a process is ongoing, but the exact percentage is unknown. ```jsx live <Layout.Stack grow space={20}> <V2ProgressBar label="isIndeterminate" isIndeterminate width={300} /> </Layout.Stack> ``` ## On cancel Use the `onCancel` prop to provide a callback function that will be called when the cancel button is clicked. This is useful for providing a way for the user to cancel the progress bar. ```jsx live () => { const [progress, setPercentage] = React.useState(95); const handleCancel = () => { setPercentage(0); console.log('Progress cancelled'); }; return ( <V2ProgressBar showProgress duration={20000} percentage={progress} onCancel={handleCancel} progressLabel={'Loading...'} label={'Progress Bar with Cancel Button'} /> ); }; ``` ## Live progress Use the `isLive` prop to set the progress bar to a live state. This is useful when the progress bar is used to indicate that a process is ongoing and updates in real time. The progress bar will fill up over time based on the updated `percentage` value. The use of the `duration` prop is optional; in this case, it determines the time it takes to fill the bar from the previous value to the new value. Note: For the `isLive` prop to work, the `percentage` prop must be updated over time. The progress bar will not fill up automatically. ```jsx live () => { const [loadProfile, setLoadProfile] = useState(false); const [percentage, setPercentage] = useState(0); const avatar = utils.useBaseUrl('/img/team/AbyssWeb/Dean-Radcliffe.jpg'); const cardImage = utils.useBaseUrl('img/graphics/card-image-example.png'); // Simulates a loading process for a user profile useEffect(() => { if (!loadProfile || percentage >= 100) return; const timer = setTimeout(() => { setPercentage((prevProgress) => { const addition = Math.floor(Math.random() * 5) + 1; const newPercentage = prevProgress + addition; return newPercentage > 100 ? 100 : newPercentage; }); }, 100); return () => clearTimeout(timer); }, [loadProfile, percentage]); const handleCancel = () => { if (percentage < 100) { setLoadProfile(false); console.log('Progress cancelled'); } }; const handleRestart = () => { setLoadProfile(true); setPercentage(0); }; const returnSkeletonStack = () => { if (!loadProfile || percentage < 100) { return ( <Layout.Stack alignItems="left"> <Layout.Group> <V2Skeleton width={50} height={50} /> <Layout.Stack> <V2Skeleton width={200} height={20} /> <V2Skeleton width={200} height={20} /> </Layout.Stack> </Layout.Group> <V2Skeleton width={260} height={100} /> </Layout.Stack> ); } return null; }; const returnContent = () => { if (loadProfile && percentage >= 100) { return ( <React.Fragment> <Layout.Stack alignItems="left"> <Layout.Group> <Layout.Group> <Box height="50px" width="50px" padding="0px" css={{ 'abyss-box-root': { backgroundImage: `url(${avatar})`, backgroundRepeat: 'no-repeat', backgroundSize: 'cover', borderRadius: '90px', }, }} /> </Layout.Group> <Layout.Group> <Layout.Stack space={0} alignItems="left"> <Text fontWeight={600}>Dean Radcliffe</Text> <Text size={'$sm'}>Sr. Engineering Manager | Abyss</Text> </Layout.Stack> </Layout.Group> </Layout.Group> <Layout.Group> <Box height="100px" width="260px" padding="0px" css={{ 'abyss-box-root': { backgroundImage: `url(${cardImage})`, backgroundRepeat: 'no-repeat', backgroundSize: 'cover', borderRadius: '10px', }, }} /> </Layout.Group> </Layout.Stack> </React.Fragment> ); } return null; }; return ( <Layout.Stack space={20} alignItems="left"> <Layout.Group alignItems="top" space={40}> <V2ProgressBar isLive showProgress progressLabel={percentage >= 100 ? 'Complete' : `(${percentage}%)`} percentage={percentage} validation={percentage >= 100 ? { type: 'success' } : undefined} label={'Loading main user profile and settings...'} /> <Layout.Group> <V2Button size="$sm" onClick={() => setLoadProfile(true)}> Load </V2Button> <V2Button size="$sm" onClick={handleCancel} variant="outline"> Pause </V2Button> <V2Button size="$sm" onClick={handleRestart} variant="outline"> Restart </V2Button> </Layout.Group> </Layout.Group> {returnContent()} {returnSkeletonStack()} </Layout.Stack> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2ProgressBar" propTypeName="V2ProgressBarProps" /> ``` ```jsx render <Docs.V2ClassesTable title="V2ProgressBar" classes={[V2ProgressBarClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> `V2ProgressBar` is a non-focusable visual component intended to display a loading state for a page, component, or process. It is therefore important to provide labels in order to provide context. Without them, screen reader users might be unaware of the progress bar or might encounter content that has no meaning. To learn more about `role="progressbar"`, see the <ExitLink href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/progressbar_role">MDN ARIA docs on the progressbar role</ExitLink>. <h2>Labels</h2> <h3>Making V2Progress bar accessible</h3> ARIA `role="progressbar"` has incomplete support by many screen readers, especially if static and unchanging (as shown below). For best screen reader accessibility: - Set V2ProgressBar.title headingLevel to nest correctly in page - This will help provide some context for the progressbar content - Define V2ProgressBar.progressLabel for non-percentage values - If V2ProgressBar displays progress other than a percentage, it is strongly recommended to use the progressLabel prop to better describe it. - V2ProgressBar.validation: Include success/error text in message - If using V2ProgressBar.validation, display a message including text indicating the state ("Completed" or "Error: "). <h3>V2ProgressBar live announcements</h3> During live updates, most screen readers (except NVDA) announce nothing. To address this, a `<p aria-live="polite">` was added to announce the progress as "##%". A separate alert is triggered (immediately) upon completion. ```jsx live () => { const [progress, setProgress] = React.useState(95); const handleCancel = () => { setProgress(0); console.log('Progress cancelled'); }; return ( <Layout.Stack grow space={30}> <V2ProgressBar label="Installation progress" subText="This may take a while (approx. 15 minutes)" showProgress percentage={10} headingLevel={1} popover={{ title: 'Installation tasks', content: 'Drivers will be updated to the latest versions. No changes to current setttings.', }} /> <V2ProgressBar label="Updating drivers" subText="Removing current drivers..." percentage={20} headingLevel={2} percentage={75} duration={7000} showProgress progressLabel={'15 of 20'} validation={{ type: 'error', message: 'Error: Unable to remove driver #16', }} /> <V2ProgressBar label="Retrying" isIndeterminate percentage={50} width={300} headingLevel={3} onCancel={handleCancel} validation={{ type: 'error', message: '' }} /> </Layout.Stack> ); }; ``` ```jsx live () => { const [loadProfile, setLoadProfile] = useState(false); const [percentage, setPercentage] = useState(0); const avatar = utils.useBaseUrl('/img/team/AbyssWeb/Bill-Tyler.png'); const cardImage = utils.useBaseUrl('img/graphics/card-image-example.png'); // Simulates a loading process for a user profile useEffect(() => { if (!loadProfile || percentage >= 100) return; const timer = setTimeout(() => { setPercentage((prevProgress) => { const addition = Math.floor(Math.random() * 10) + 1; const newPercentage = prevProgress + addition; return newPercentage > 100 ? 100 : newPercentage; }); }, 100); return () => clearTimeout(timer); }, [loadProfile, percentage]); const handleCancel = () => { if (percentage < 100) { setLoadProfile(false); console.log('Progress cancelled'); } }; const handleRestart = () => { setLoadProfile(true); setPercentage(0); }; const returnSkeletonStack = () => { if (!loadProfile || percentage < 100) { return ( <Layout.Stack alignItems="left"> <Layout.Group> <V2Skeleton width={50} height={50} loadingText="Searching Abyss team members" /> <Layout.Stack> <V2Skeleton width={200} height={20} loadingText=" " /> <V2Skeleton width={200} height={20} loadingText=" " /> </Layout.Stack> </Layout.Group> </Layout.Stack> ); } return null; }; const returnContent = () => { if (loadProfile && percentage >= 100) { return ( <React.Fragment> <Layout.Stack alignItems="left"> <Layout.Group> <Layout.Group> <Box height="50px" width="50px" padding="0px" css={{ 'abyss-box-root': { backgroundImage: `url(${avatar})`, backgroundRepeat: 'no-repeat', backgroundSize: 'cover', borderRadius: '90px', }, }} /> </Layout.Group> <Layout.Group> <Layout.Stack space={0} alignItems="left"> <Text fontWeight={600}>Bill Tyler</Text> <Text size={'$sm'}>Principal A11y Engineer| ACoE</Text> </Layout.Stack> </Layout.Group> </Layout.Group> </Layout.Stack> </React.Fragment> ); } return null; }; return ( <Layout.Stack space={20} alignItems="left"> <Layout.Group alignItems="top" space={40}> <V2ProgressBar isLive showProgress progressLabel={percentage >= 100 ? 'Complete' : `${percentage}%`} percentage={percentage} validation={ percentage >= 100 ? { type: 'success', message: 'Complete' } : undefined } label={'Find Abyss Web accessibility resource(s)'} /> <Layout.Group> <V2Button size="$sm" onClick={() => setLoadProfile(true)}> Load </V2Button> <V2Button size="$sm" onClick={handleCancel} variant="outline"> Pause </V2Button> <V2Button size="$sm" onClick={handleRestart} variant="outline"> Restart </V2Button> </Layout.Group> </Layout.Group> {returnContent()} {returnSkeletonStack()} </Layout.Stack> ); }; ``` <h2>Screen Reader Support (7/10/2025)</h2> Though both the [HTML \<progress\> tag](https://www.w3schools.com/tags/tag_progress.asp) and [WAI-ARIA role="progressbar"](https://www.w3.org/TR/wai-aria-1.1/#progressbar) have been defined for some time, screen reader for support for them is minimal to non-existent. This includes the expected aria-live behaviors to announce status updates. <h3>Windows</h3> - Both NVDA and JAWS - Support `<progress>` and `role="progressbar"` - Support `aria-valuetext` - Do not support `aria-describedby` - NVDA - Announces updates to `aria-valuenow` as a tone that rises with percentage - Only supports `aria-label`; ignores `<label>` and `aria-labelledby` - JAWS - Does not support updates to aria-valuenow - Ignores all but role and value - Does not support `<label>`, `aria-label`, or `aria-labelledby` <h3>Mac</h3> - VoiceOver - Does not support updates to `aria-valuenow` - Supports `<progress>` and `role="progressbar"` - Supports `<label>`, `aria-label`, and `aria-labelledby` - Supports `aria-valuetext` - Supports `aria-describedby` <h3>Screen Reader Experience</h3> To make this component accessible, some props are used to provide the necessary status updates. If they are not used, off-screen equivalents are used. - `progressLabel` - live region - When visible, progressLabel text is announced on each update - If not visible, a progressLabel is created off-screen using ##% - For best screen reader experience - Keep content short, ideally without parentheses - Example: Use ##% not (##%) - If possible, space out progressLabel updates so they are 2-3 seconds apart - Rapid-fire updates lead to backlogged announcements ("1% 2% 3% 4% 5% ...") - Validation messages - alerts - When using validation: - If `validation.message` is defined, its text is announced as part of an alert when displayed - If not, an off-screen `validation.message` alert is created - These announce - "Complete" for Success - "Error" for Error - As off-screen content, they also provide text alternatives for the bar and icon </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={'V2ProgressBar'} keys={['progressBarV2']} /> ``` </Tab> --- id: progress-bar category: Feedback title: ProgressBar description: Used to show users the status of loading an app, ongoing processes, saving changes/updates, and more. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=34258-115837 subDirectory: ProgressBar/v1 --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="ProgressBar"></Docs.V2MigrationBanner> ``` ```jsx import { ProgressBar } from '@uhg-abyss/web/ui/ProgressBar'; ``` ```jsx sandbox { component: 'ProgressBar', inputs: [ { prop: 'label', type: 'string', }, { prop: 'subText', type: 'string', }, { prop: 'minLabel', type: 'string', }, { prop: 'maxLabel', type: 'string', }, { prop: 'barColor', type: 'string', }, { prop: 'fillColor', type: 'string', }, { prop: 'height', type: 'string', }, { prop: 'width', type: 'string', }, { prop: 'duration', type: 'number', }, { prop: 'percentage', type: 'number', }, { prop: 'showProgress', type: 'boolean', }, { prop: 'progressLabel', type: 'string', }, ] } <ProgressBar percentage={25} /> ``` ## Color Use the `fillColor` prop to change the color of the progress bar fill bar. Use the `barColor` prop to change the background color of the progress bar. ```jsx live <ProgressBar percentage={25} fillColor="$interactive1" barColor="$gray4" /> ``` ## Labels Use the `label` and `subText` props to provide information above the progress bar. Use the `minLabel` and `maxLabel` props to set the beginning and ending labels for the progress bar. It is strongly recommended to provide a `label` to progress bars to provide context around the progress bar. See the [Accessibility tab](/web/ui/progress-bar?tab=accessibility) for more information. ```jsx live <ProgressBar label="Label" subText="subtext" percentage={75} minLabel="$0.00" maxLabel="$2000.00" progressLabel="$1500.00" showProgress /> ``` ### Label offset For better screen reader support, the label element is treated as a [Heading](/web/ui/heading). Use the `labelOffset` prop to manually adjust the heading level. By default, the label is a level one heading (`<h1>`). To learn more about heading offsets, see the [Heading docs](/web/ui/heading/#offset). See the [Accessibility tab](/web/ui/progress-bar?tab=accessibility) for more information. ```jsx live <ProgressBar label="Label" labelOffset={1} percentage={30} /> ``` ## Show progress Use the `showProgress` prop to display the percentage number at the end of the filled progress bar space. ```jsx live <ProgressBar percentage={25} showProgress /> ``` ## Progress label If `showProgress` is true, the label shown defaults to the percentage the progress bar is filled. Use the `progressLabel` prop to provide a custom label in place of this. Doing so is strongly recommended if the progress bar is used to display any value that is not a percentage. Note: If the text doesn't fit in the progress bar, it will not be shown. See the example below with the same `progressLabel`, but different `percentage`. ```jsx live <> <Text>Percentage = 5%</Text> <ProgressBar percentage={5} showProgress progressLabel="Super Long Label Inside Progress Bar" /> </> ``` ```jsx live <> <Text>Percentage = 40%</Text> <ProgressBar percentage={40} showProgress progressLabel="Super Long Label Inside Progress Bar" /> </> ``` ## Duration Use the `duration` prop to set the time it takes in milliseconds for the fill bar to reach the set percentage. The default is set to `0`. ```jsx live <ProgressBar percentage={50} duration={5000} /> ``` ## Width Use the `width` property to set the width of the bar. The default width is set to `100%`. ```jsx live <React.Fragment> <ProgressBar percentage={25} /> <br /> <ProgressBar percentage={25} width="75%" /> </React.Fragment> ``` ## Height Use the`height` property to set the width and height of the bar. The default height is set to `20`. ```jsx live <React.Fragment> <ProgressBar percentage={25} /> <br /> <ProgressBar percentage={25} height={50} /> </React.Fragment> ``` ## Border radius Use the `borderRadius` prop to change the border radius of the bar. The default is set to `3`. ```jsx live <ProgressBar percentage={25} borderRadius={10} /> ``` ## Visually hidden labels Use `hideLabel`, `hideMinLabel`, and `hideMaxLabel` to visually hide the corresponding labels. Labels will still be accessible to screen readers. ```jsx live <ProgressBar percentage={25} label="visually hidden label" minLabel="visually hidden minLabel" maxLabel="visually hidden maxLabel" hideLabel hideMinLabel hideMaxLabel /> ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={ProgressBar} rows={[ { name: 'percentage', type: 'number', description: 'The percent of the bar to be filled', }, { name: 'styles', type: 'object', description: 'Added styles to the progress bar', }, { name: 'duration', type: 'number', description: 'Duration of the progress bar animation', }, { name: 'width', type: 'number | string', description: 'Width of the progress bar', }, { name: 'minLabel', type: 'string', description: 'Starting label on the progress bar', }, { name: 'maxLabel', type: 'string', description: 'Ending label on the progress bar', }, { name: 'height', type: 'number', description: 'Height of the progress bar', }, { name: 'borderRadius', type: 'string', description: 'Border radius of the progress bar', }, { name: 'barColor', type: 'string', description: 'Color of the progress fill bar', }, { name: 'fillColor', type: 'string', description: 'Background color of the progress bar', }, { name: 'labelOffset', type: 'number', description: '0 | 1 | 2 | 3 | 4 | 5. Offset of label heading. See Heading docs for more details', }, { name: 'label', type: 'string', description: 'Label for progress bar', }, { name: 'subText', type: 'string', description: 'Label subtext for progress bar', }, { name: 'showProgress', type: 'boolean', description: 'Display percentage in filled progress bar space', }, { name: 'title', type: 'string', description: 'String used for the descriptive accessible name', }, { name: 'progressLabel', type: 'string', description: 'display value in filled progress bar space', }, { name: 'hideLabel', type: 'boolean', description: 'use to visually hide label', }, { name: 'hideMinLabel', type: 'boolean', description: 'use to visually hide minLabel', }, { name: 'hideMaxLabel', type: 'boolean', description: 'use to visually hide maxLabel', }, { name: 'balanceLabel', type: 'string', description: 'Balance label on the progress bar', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={ProgressBar} rows={[ { name: 'progress-bar-root', description: 'Progress Bar root element', }, { name: 'progress-bar-filler', description: 'Progress bar fill', }, { name: 'progress-bar-min-label', description: 'Min label', }, { name: 'progress-bar-max-label', description: 'Max label', }, { name: 'progress-bar-label', description: 'Top label', }, { name: 'progress-bar-subtext', description: 'Top subtext', }, { name: 'progress-bar-show-progress-container', description: 'progress label container', }, { name: 'progress-bar-show-progress', description: 'progress label', }, ]} /> ``` </Tab> <Tab label="Accessibility"> ProgressBar is a non-focusable visual component intended to display a loading state for a page, component, or process. It is therefore important to provide labels in order to provide context. Without them, screen reader users might be unaware of the progress bar or might encounter content that has no meaning. To learn more about `role="progressbar"`, see the <ExitLink href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/progressbar_role">MDN ARIA docs on the progressbar role</ExitLink>. <h2>Labels</h2> <h3>Labels as Headings</h3> For better screen reader support, particularly for JAWS, the label element is treated as a [Heading](/web/ui/heading), and is a level one heading (`<h1>`) by default. It is therefore important that the heading level be adjusted according to the component's position on the page such that it's heading level is no less than one level below the previous heading. The `labelOffset` prop allows the heading level to be set manually, but the [Heading.Level](/web/ui/heading/#usage) wrapper will automatically set the level based on how nested the component is, just as with a regular Heading. ```jsx live <React.Fragment> <ProgressBar label="H1 Label" percentage={10} /> <br /> <Heading.Level> <ProgressBar label="H2 Label" percentage={20} /> <br /> <Heading.Level> <ProgressBar label="H3 Label" percentage={30} /> </Heading.Level> </Heading.Level> </React.Fragment> ``` <h3>Progress Label</h3> If a ProgressBar is used to display information other than a percentage, it is strongly recommended to use the `progressLabel` prop to provide extra context. ```jsx live () => { const totalPages = 20; const livePages = 15; return ( <ProgressBar label="Live Pages" percentage={(livePages / totalPages) * 100} minLabel="0" maxLabel={`${totalPages}`} showProgress progressLabel={`${livePages} Page(s)`} /> ); }; ``` <h2>Color</h2> While the `fillColor` and `barColor` props allow designers and developers to customize the color of the progress bar, it is important to remember that certain color combinations are not accessible. Consider the following: ```jsx live <React.Fragment> <ProgressBar percentage={50} fillColor="$gray5" barColor="$gray4" label="Not accessible" subText="Fill color is too similar to bar color (1.89:1)" /> <br /> <ProgressBar percentage={50} fillColor="$gray4" label="Not accessible" subText="Progress label is too similar to fill color (1.6:1)" showProgress /> <br /> <ProgressBar percentage={50} label="Accessible" subText="All colors are distinct enough from one another" showProgress /> </React.Fragment> ``` When overriding the default colors, keep the following in mind: - As a non-text contrast, the `fillColor` must have at least a 3:1 color contrast with the `barColor`. - As a text contrast, the `fillColor` must have at least a 4.5:1 color contrast with the progress label color, which is white. To learn more about color use, see the [Accessibility section](/web/brand/uhc/colors/#accessibility) on the Colors page. <h2>Screen Reader Support</h2> Unfortunately, various screen readers handle progress bars in different ways, which may lead to some unexpected behavior for screen reader users. Below is a list of known issues for progress bar support as of 1/1/2024. <h3>Windows</h3> - Both NVDA and JAWS - Support `<progress>` and `role="progressbar"` - Support `aria-valuetext` - Do not support `aria-describedby` - NVDA - Only supports `aria-label`; ignores `<label>` and `aria-labelledby` - JAWS - Ignores all but `role` and `value` - Does not support `<label>`, `aria-label`, or `aria-labelledby` <h3>Mac</h3> - VoiceOver - Supports `<progress>` but not `role="progressbar"` - Supports `<label>`, `aria-label`, and `aria-labelledby` - Supports `aria-valuetext` - Supports `aria-describedby` </Tab> --- id: radio-group-v2 category: Forms title: V2RadioGroup description: Provides a set of checkable buttons, known as radio buttons, where no more than one of the buttons can be checked at a time. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=10774-2830 subDirectory: RadioGroup/v2 sourceIsTS: true --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="RadioGroup"></Docs.V2MigrationBanner> ``` ```jsx import { V2RadioGroup } from '@uhg-abyss/web/ui/RadioGroup'; ``` ```jsx sandbox { component: 'V2RadioGroup', inputs: [ { prop: 'label', type: 'string', }, { prop: 'errorMessage', type: 'string', }, { prop: 'subText', type: 'string', }, { prop: 'hideLabel', type: 'boolean', }, ] } () => { const [radioValue, setRadioValue] = useState('one'); console.log('radioValue', radioValue); return ( <V2RadioGroup label="Radio Sandbox" subText="This is subtext" onChange={(e) => setRadioValue(e.target.value)} value={radioValue} > <V2RadioGroup.Column> <V2RadioGroup.Radio label="One" value="one" /> <V2RadioGroup.Radio label="Two" value="two" /> <V2RadioGroup.Radio label="Three" value="three" /> <V2RadioGroup.Radio label="Four" value="four" /> </V2RadioGroup.Column> <V2RadioGroup.Column> <V2RadioGroup.Radio label="Five" value="five" /> <V2RadioGroup.Radio label="Six" value="six" /> <V2RadioGroup.Radio label="Seven" value="seven" /> <V2RadioGroup.Radio label="Eight" value="eight" /> </V2RadioGroup.Column> </V2RadioGroup> ); }; ``` ## useFormV2 (recommended) Using the `useFormV2` hook lets the DOM handle form data. ```jsx live () => { const form = useFormV2({ defaultValues: { 'radio-form': 'two', }, }); const onSubmit = (data) => { console.log('submitted', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2RadioGroup label="V2RadioGroup useFormV2" model="radio-form" validators={{ required: true }} > <V2RadioGroup.Column> <V2RadioGroup.Radio label="One" value="one" /> <V2RadioGroup.Radio label="Three" value="three" /> </V2RadioGroup.Column> <V2RadioGroup.Column> <V2RadioGroup.Radio label="Two" value="two" /> <V2RadioGroup.Radio label="Four" value="four" /> </V2RadioGroup.Column> </V2RadioGroup> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [radioValue, setRadioValue] = useState(''); console.log('radioValue', radioValue); return ( <V2RadioGroup label="Radio useState" onChange={(e) => setRadioValue(e.target.value)} value={radioValue} > <V2RadioGroup.Column> <V2RadioGroup.Radio label="One" value="one" /> <V2RadioGroup.Radio label="Three" value="three" /> </V2RadioGroup.Column> <V2RadioGroup.Column> <V2RadioGroup.Radio label="Two" value="two" /> <V2RadioGroup.Radio label="Four" value="four" /> </V2RadioGroup.Column> </V2RadioGroup> ); }; ``` ## V2RadioGroup.Column The radio group is organized into `V2RadioGroup.Column` subcomponents. Each `V2RadioGroup.Radio` in required to be wrapped in a `V2RadioGroup.Column` when using `V2RadioGroup`. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', variants: { direction: { row: { flexDirection: 'row', }, }, }, }), [] ); const form = useFormV2({}); return ( <V2FormProvider state={form}> <FormSpacing> <FormSpacing direction="row"> <V2RadioGroup label="One Column" model="oneCol"> <V2RadioGroup.Column> <V2RadioGroup.Radio label="Option 1" value="one" /> <V2RadioGroup.Radio label="Option 2" value="two" /> <V2RadioGroup.Radio label="Option 3" value="three" /> </V2RadioGroup.Column> </V2RadioGroup> <V2RadioGroup label="Two Columns" model="twoCol"> <V2RadioGroup.Column> <V2RadioGroup.Radio label="Option 1" value="one" /> <V2RadioGroup.Radio label="Option 2" value="two" /> <V2RadioGroup.Radio label="Option 3" value="three" /> </V2RadioGroup.Column> <V2RadioGroup.Column> <V2RadioGroup.Radio label="Option 4" value="four" /> <V2RadioGroup.Radio label="Option 5" value="five" /> <V2RadioGroup.Radio label="Option 6" value="six" /> </V2RadioGroup.Column> </V2RadioGroup> <V2RadioGroup label="Three Columns" model="threeCol"> <V2RadioGroup.Column> <V2RadioGroup.Radio label="Option 1" value="one" /> <V2RadioGroup.Radio label="Option 2" value="two" /> <V2RadioGroup.Radio label="Option 3" value="three" /> </V2RadioGroup.Column> <V2RadioGroup.Column> <V2RadioGroup.Radio label="Option 4" value="four" /> <V2RadioGroup.Radio label="Option 5" value="five" /> <V2RadioGroup.Radio label="Option 6" value="six" /> </V2RadioGroup.Column> <V2RadioGroup.Column> <V2RadioGroup.Radio label="Option 7" value="seven" /> <V2RadioGroup.Radio label="Option 8" value="eight" /> <V2RadioGroup.Radio label="Option 9" value="nine" /> </V2RadioGroup.Column> </V2RadioGroup> </FormSpacing> <V2RadioGroup label="Four Columns" model="fourCol"> <V2RadioGroup.Column> <V2RadioGroup.Radio label="Option 1" value="one" /> </V2RadioGroup.Column> <V2RadioGroup.Column> <V2RadioGroup.Radio label="Option 2" value="two" /> </V2RadioGroup.Column> <V2RadioGroup.Column> <V2RadioGroup.Radio label="Option 3" value="three" /> </V2RadioGroup.Column> <V2RadioGroup.Column> <V2RadioGroup.Radio label="Option 4" value="four" /> </V2RadioGroup.Column> </V2RadioGroup> </FormSpacing> </V2FormProvider> ); }; ``` ## Label Every `V2RadioGroup` must have a label to be accessible. Use the `label` prop to change the displayed label for the group. Set `hideLabel` to `true` to visibly hide the label but retain accessibility. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2({}); return ( <V2FormProvider state={form}> <FormSpacing> <V2RadioGroup label="Label visible" model="label-visible"> <V2RadioGroup.Radio label="One" value="one" /> <V2RadioGroup.Radio label="Two" value="two" /> </V2RadioGroup> <V2RadioGroup label="Label hidden" model="label-hidden" hideLabel> <V2RadioGroup.Radio label="One" value="one" /> <V2RadioGroup.Radio label="Two" value="two" /> </V2RadioGroup> </FormSpacing> </V2FormProvider> ); }; ``` ## Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip-v2) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip-v2) or a [Popover](/web/ui/popover-v2). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip-v2#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2({}); return ( <V2FormProvider state={form}> <FormSpacing> <V2RadioGroup label="Helper with Tooltip" model="helper-tooltip" helper="This is a tooltip helper" > <V2RadioGroup.Radio label="One" value="one" /> <V2RadioGroup.Radio label="Two" value="two" /> </V2RadioGroup> <V2RadioGroup label="Helper with Popover" model="helper-popover" helper={ <V2Popover title="Custom Helper" content="This is a popover with a custom icon" > <IconSymbol icon="help" variant="outlined" color="$success1" size="$md" /> </V2Popover> } > <V2RadioGroup.Radio label="One" value="one" /> <V2RadioGroup.Radio label="Two" value="two" /> </V2RadioGroup> </FormSpacing> </V2FormProvider> ); }; ``` ## Subtext Use the `subText` prop to display helpful information related to the input field. The prop accepts either a string or an object of the form: ```ts { text: string; position: 'above' | 'below'; } ``` The `position` property determines where the subtext will be displayed in relation to the input field. The default value is `'below'`. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2({}); const onSubmit = (data) => { console.log('submitted', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <FormSpacing> <V2RadioGroup label="V2RadioGroup" model="radio-form" subText={{ text: 'Subtext passed above the input', position: 'above', }} > <V2RadioGroup.Column> <V2RadioGroup.Radio label="One" value="one" /> <V2RadioGroup.Radio label="Two" value="two" /> </V2RadioGroup.Column> </V2RadioGroup> <V2RadioGroup label="V2RadioGroup" model="radio-form2" subText="Regular Subtext" > <V2RadioGroup.Column> <V2RadioGroup.Radio label="One" value="one" /> <V2RadioGroup.Radio label="Two" value="two" /> </V2RadioGroup.Column> </V2RadioGroup> </FormSpacing> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ## Validation ```jsx render <Docs.FormCompatibilityWidget useForm /> ``` Use the `validators` prop to provide validation rules, such as `required`. Note: The default error message when `required` is `true` is minimally acceptable for accessibility. It is highly recommended to customize it to be more specific to the use of the field and form. ```jsx live () => { const form = useFormV2({}); const onSubmit = (data) => { console.log('submitted', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2RadioGroup label="V2RadioGroup useFormV2" model="radio-form" validators={{ required: true }} > <V2RadioGroup.Column> <V2RadioGroup.Radio label="One" value="one" /> <V2RadioGroup.Radio label="Three" value="three" /> </V2RadioGroup.Column> <V2RadioGroup.Column> <V2RadioGroup.Radio label="Two" value="two" /> <V2RadioGroup.Radio label="Four" value="four" /> </V2RadioGroup.Column> </V2RadioGroup> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ## Error message ```jsx render <Docs.FormCompatibilityWidget useState /> ``` Use the `errorMessage` prop to display a custom error message below the radio group. Note: The errorMessage prop does not work with useFormV2 and is only applicable within our form input components when useState is being utilized. See the [useFormV2 Docs](/web/hooks/use-form-v2#set-error) for example use cases with useFormV2. ```jsx live () => { const [radioValue, setRadioValue] = useState(''); return ( <V2RadioGroup label="Error Message" value={radioValue} onChange={(e) => setRadioValue(e.target.value)} errorMessage="Error Message" > <V2RadioGroup.Radio label="One" value="one" /> <V2RadioGroup.Radio label="Two" value="two" /> <V2RadioGroup.Radio label="Three" value="three" /> </V2RadioGroup> ); }; ``` ## Success message ```jsx render <Docs.FormCompatibilityWidget useForm useState /> ``` Use the `successMessage` prop to insert a custom success message below the radio group that will display when the form submission is successful. ```jsx live () => { const form = useFormV2({ defaultValues: { 'radio-form': 'two', }, }); const onSubmit = (data) => { console.log('submitted', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2RadioGroup label="V2RadioGroup useFormV2" model="radio-form" validators={{ required: true }} successMessage="Success! Form submitted." > <V2RadioGroup.Column> <V2RadioGroup.Radio label="One" value="one" /> <V2RadioGroup.Radio label="Three" value="three" /> </V2RadioGroup.Column> <V2RadioGroup.Column> <V2RadioGroup.Radio label="Two" value="two" /> <V2RadioGroup.Radio label="Four" value="four" /> </V2RadioGroup.Column> </V2RadioGroup> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ## Disabled Set the `isDisabled` prop to `true` to disable all radios in the group. Individual radios can be disabled by setting `isDisabled` to `true` in their respective `V2Radio` instead of the outer component. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2({ defaultValues: { disabled: 'dis1', disabled2: 'dis6', }, }); return ( <V2FormProvider state={form}> <FormSpacing> <V2RadioGroup isDisabled label="All Radios Disabled" model="disabled"> <V2RadioGroup.Radio value="dis1" label="Disabled 1" /> <V2RadioGroup.Radio value="dis2" label="Disabled 2" /> <V2RadioGroup.Radio value="dis3" label="Disabled 3" /> <V2RadioGroup.Radio value="dis4" label="Disabled 4" /> </V2RadioGroup> <V2RadioGroup label="Individual Radios Disabled" model="disabled2"> <V2RadioGroup.Radio value="dis5" label="Disabled 1" isDisabled /> <V2RadioGroup.Radio value="dis6" label="Enabled 1" /> <V2RadioGroup.Radio value="dis7" label="Disabled 2" isDisabled /> <V2RadioGroup.Radio value="dis8" label="Enabled 2" /> </V2RadioGroup> </FormSpacing> </V2FormProvider> ); }; ``` ## Multi-line wrapping The `label` for each radio button has a maximum width of `743px`. After that, the text will wrap. ```jsx live () => { const [radioValue, setRadioValue] = useState('one'); return ( <V2RadioGroup label="Label wrapping" onChange={(e) => setRadioValue(e.target.value)} value={radioValue} > <V2RadioGroup.Column> <V2RadioGroup.Radio label="Lorem ipsum dolor sit amet consectetur adipiscing elit. Consectetur adipiscing elit quisque faucibus ex sapien vitae. Ex sapien vitae pellentesque sem placerat in id. Placerat in id cursus mi pretium tellus duis. Pretium tellus duis convallis tempus leo eu aenean." value="one" /> <V2RadioGroup.Radio label="Two" value="two" /> <V2RadioGroup.Radio label="Three" value="three" /> <V2RadioGroup.Radio label="Four" value="four" /> </V2RadioGroup.Column> </V2RadioGroup> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2RadioGroup" propTypeName="V2RadioGroupProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="V2Radio" propTypeName="V2RadioProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="V2RadioGroupColumn" propTypeName="V2RadioGroupColumnProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2ClassesTable title="V2RadioGroup" classes={[V2RadioGroupClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2Radio" classes={[V2RadioClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2RadioGroupColumn" classes={[V2RadioGroupColumnClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> A radio group is a set of checkable buttons, known as radio buttons, where no more than one of the buttons can be checked at a time. Some implementations may initialize the set with all buttons in the unchecked state in order to force the user to check one of the buttons before moving past a certain point in the workflow. The component adheres to standard HTML practices by correctly implementing `<fieldset>`, `<legend>`, and `<input type="radio">` elements. By wrapping the radio buttons within a `<fieldset>` element, the component groups them together, providing semantic structure and an accessible boundary recognized by screen readers. A `<legend>` element is used within the `<fieldset>` to offer a descriptive label, aiding users, especially those utilizing screen readers, in understanding the context of the radio buttons. Each radio button is implemented as an `<input type="radio">` element, ensuring proper behavior and interaction as expected in a web form. The component's input wrapper has a `role="radiogroup"` attribute, which is essential for screen readers to identify the group of radio buttons and further allow the usage of `aria-required` and `aria-invalid` inside the component. For more details, please visit the following: - [TPGi's Required Groups](https://www.tpgi.com/everythings-more-complicated-in-groups-required-groups/) - [Marking Support](https://adrianroselli.com/2022/02/support-for-marking-radio-buttons-required-invalid.html) #### Differences from common group implementations Required and error reporting are associated with the group `<fieldset>`, not the radio buttons. This is to more clearly associate errors and requirements with the group. Otherwise, unlike `<select>` (which is very similar), one or all of the individual radio buttons might be mistakenly considered "required" or "invalid." Another difference is that though `<legend>` is used to label the grouping, aria-labelledby is also used in `<fieldset>`. This is necessary since, according to HTML standards, `<legend>` must be the first child of `<fieldset>`. Since presentation requires wrapping `<legend>` with `<div>`s, aria-labelledby is used to "patch" the broken relationship and ensure the grouping has an accessible name. For more details on these HTML elements and their usage, please visit the following W3Schools links: - [HTML <fieldset>](https://www.w3schools.com/tags/tag_fieldset.asp) - [HTML <legend>](https://www.w3schools.com/tags/tag_legend.asp) - [HTML <input type="radio">](https://www.w3schools.com/tags/att_input_type_radio.asp) Adheres to the <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/radio/">Radio Group WAI-ARIA design pattern</ExitLink>. ```jsx live () => { const form = useFormV2({ defaultValues: {}, }); const onSubmit = (data) => { console.log('submitted', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2RadioGroup label="Scoops of ice cream" model="radio-form" subText="Today's flavor is Chocolate" validators={{ required: true }} > <V2RadioGroup.Radio label="One" value="one" /> <V2RadioGroup.Radio label="Two" value="two" /> <V2RadioGroup.Radio label="Three" value="three" /> <V2RadioGroup.Radio label="Four (maximum)" value="four" /> <V2RadioGroup.Radio label="None (I don't want any ice cream)" value="none" /> </V2RadioGroup> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Tab', description: 'Moves focus to either the checked radio item or the first radio item in the group.', }, { name: 'Space', description: 'When focus is on an unchecked radio item, checks it.', }, { name: 'Enter', description: 'When focus is on an unchecked radio item, checks it.', }, { name: 'Arrow Down', description: 'Moves focus to the next radio item in the group.', }, { name: 'Arrow Right', description: 'Moves focus to the next radio item in the group.', }, { name: 'Arrow Up', description: 'Moves focus to the previous radio item in the group.', }, { name: 'Arrow Left', description: 'Moves focus to the previous radio item in the group.', }, ]} /> ``` </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={'V2RadioGroup'} keys={['radioGroupV2']} /> ``` </Tab> --- id: radio-group category: Forms title: RadioGroup description: Provides a set of checkable buttons, known as radio buttons, where no more than one of the buttons can be checked at a time. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=510-11899 --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="RadioGroup"></Docs.V2MigrationBanner> ``` ```jsx import { RadioGroup } from '@uhg-abyss/web/ui/RadioGroup'; ``` ```jsx sandbox { component: 'RadioGroup', inputs: [ { prop: 'label', type: 'string', }, { prop: 'errorMessage', type: 'string', }, { prop: 'subText', type: 'string', }, { prop: 'size', type: 'string', }, { prop: 'display', type: 'select', options: [ { label: 'column', value: 'column' }, { label: 'row', value: 'row' }, ], }, { prop: 'hideLabel', type: 'boolean', }, ] } () => { const [radioValue, setRadioValue] = useState('one'); console.log('radioValue', radioValue); return ( <RadioGroup label="Radio Sandbox" onChange={(e) => setRadioValue(e.target.value)} value={radioValue} subText="This is subtext" > <RadioGroup.Radio label="One" value="one" /> <RadioGroup.Radio label="Two" value="two" /> <RadioGroup.Radio label="Three" value="three" /> <RadioGroup.Radio label="Four" value="four" /> </RadioGroup> ); }; ``` ## useForm (recommended) Using the `useForm` hook lets the DOM handle form data. ```jsx live () => { const form = useForm({ defaultValues: { 'radio-form': 'two', }, }); const onSubmit = (data) => { console.log('submitted', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <RadioGroup label="RadioGroup useForm" model="radio-form" validators={{ required: true }} > <RadioGroup.Radio label="One" value="one" /> <RadioGroup.Radio label="Two" value="two" /> <RadioGroup.Radio label="Three" value="three" /> <RadioGroup.Radio label="Four" value="four" /> </RadioGroup> <Button type="submit" style={{ marginTop: 15 }}> Submit </Button> </FormProvider> ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [radioValue, setRadioValue] = useState('one'); console.log('radioValue', radioValue); return ( <RadioGroup label="Radio useState" onChange={(e) => setRadioValue(e.target.value)} value={radioValue} > <RadioGroup.Radio label="One" value="one" /> <RadioGroup.Radio label="Two" value="two" /> <RadioGroup.Radio label="Three" value="three" /> <RadioGroup.Radio label="Four" value="four" /> </RadioGroup> ); }; ``` ## Label and subtext Label is required, but subtext is not. Set the `label` prop to change the displayed label for the group. Pass `hideLabel` to visibly hide label but retain accessibility. Use the `subText` prop to display helpful text below the radio group. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <RadioGroup label="Label and Subtext" subText="Subtext" model="label-visible" > <RadioGroup.Radio label="One" value="one" /> <RadioGroup.Radio label="Two" value="two" /> </RadioGroup> <RadioGroup label="Label only" model="label-visible"> <RadioGroup.Radio label="One" value="one" /> <RadioGroup.Radio label="Two" value="two" /> </RadioGroup> <RadioGroup label="Hidden Label" hideLabel subText="Subtext only" model="label-hidden" > <RadioGroup.Radio label="One" value="one" /> <RadioGroup.Radio label="Two" value="two" /> </RadioGroup> </FormProvider> ); }; ``` ## Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip) or a [Popover](/web/ui/popover). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <RadioGroup label="Default Helper" helper="This is a tooltip" model="helper-tooltip" > <RadioGroup.Radio label="One" value="one" /> <RadioGroup.Radio label="Two" value="two" /> </RadioGroup> <RadioGroup label="Custom Helper" helper={ <Popover title="Custom Helper" content="This is a popover with a custom icon" > <IconSymbol icon="help" variant="outlined" color="$success1" size="$sm" /> </Popover> } model="helper-custom" validators={{ required: true }} > <RadioGroup.Radio label="One" value="one" /> <RadioGroup.Radio label="Two" value="two" /> </RadioGroup> </FormProvider> ); }; ``` ## Error message Use the `errorMessage` prop to display a custom error message below the radio group. Note: The errorMessage prop does not work with useForm and is only applicable within our form input components when useState is being utilized. See the [useForm Docs](/web/hooks/use-form#set-error) for example use cases with useForm. ```jsx live () => { const [radioValue, setRadioValue] = useState(''); return ( <RadioGroup label="Error Message" value={radioValue} onChange={(e) => setRadioValue(e.target.value)} errorMessage="Error Message" > <RadioGroup.Radio label="One" value="one" /> <RadioGroup.Radio label="Two" value="two" /> <RadioGroup.Radio label="Three" value="three" /> </RadioGroup> ); }; ``` ## Descriptors display Use the `descriptorsDisplay` prop to set the orientation of the error message and subtext descriptor content. Available variants include 'column' and 'row'. The default is set to 'row'. Use the [FormProvider](/web/ui/form-provider#descriptors-display) and `descriptorsDisplay` to set the descriptors orientation across an entire form. ```jsx live () => { const [radioValue, setRadioValue] = useState(''); return ( <RadioGroup value={radioValue} onChange={(e) => setRadioValue(e.target.value)} label="Descriptors Display" subText="Subtext Message" errorMessage="Error Message" descriptorsDisplay="column" > <RadioGroup.Radio label="One" value="one" /> <RadioGroup.Radio label="Two" value="two" /> <RadioGroup.Radio label="Three" value="three" /> </RadioGroup> ); }; ``` ## Disabled Set the `isDisabled` prop to `true` to disable all radios in the group. Individual radios can be disabled by setting `isDisabled` to `true` in their respective `RadioGroup.Radio` instead of the outer component. ```jsx live () => { const form = useForm({}); return ( <FormProvider state={form}> <RadioGroup isDisabled label="All Radios Disabled" model="disabled"> <RadioGroup.Radio value="dogs" label="Disabled 1" /> <RadioGroup.Radio value="cats" label="Disabled 2" /> <RadioGroup.Radio value="cats1" label="Disabled 3" /> <RadioGroup.Radio value="cats2" label="Disabled 4" /> </RadioGroup> <RadioGroup label="Individual Radios Disabled" model="disabled2"> <RadioGroup.Radio value="dogs" label="Disabled 1" isDisabled /> <RadioGroup.Radio value="cats" label="Enabled 1" /> <RadioGroup.Radio value="cats1" label="Disabled 2" isDisabled /> <RadioGroup.Radio value="cats2" label="Enabled 2" /> </RadioGroup> </FormProvider> ); }; ``` ## Display Use the `display` prop to set the direction a group of radio buttons appear. The default is set to `'column'`. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <RadioGroup label="RadioGroup Column" model="column"> <RadioGroup.Radio label="Column A" value="A" /> <RadioGroup.Radio label="Column B" value="B" /> </RadioGroup> <RadioGroup display="row" label="RadioGroup Row" model="row"> <RadioGroup.Radio label="Row A" value="A" /> <RadioGroup.Radio label="Row B" value="B" /> </RadioGroup> </FormProvider> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={RadioGroup} rows={[ { name: 'children', type: 'ReactNode', description: 'The contents of the radio group component', }, { name: 'label', type: 'string', description: 'Set the label of the radio group', }, { name: 'helper', type: 'node | string', description: 'Helper element next to label', }, { name: 'value', type: 'string', description: 'Value that is selected', }, { name: 'model', type: 'string', description: 'Unique identifier used for FormProvider', }, { name: 'errorMessage', type: 'string', description: 'Set the error message', }, { name: 'validators', type: 'shape', description: 'Rules for radio validation', }, { name: 'size', type: 'number | string', description: 'Set the size of the radio group', }, { name: 'display', type: 'string', description: 'Set the direction a group of radio buttons are displayed', }, { name: 'hideLabel', type: 'boolean', description: 'Flag to hide label', }, { name: 'isDisabled', type: 'boolean', description: 'Flag to set if a radio group is disabled', }, { name: 'onChange', type: 'function', description: 'Callback fired every time the value changes', }, { name: 'onFocus', type: 'function', description: 'Callback fired everytime the component is focused', }, { name: 'onBlur', type: 'function', description: 'Callback fired everytime the component is unfocused', }, { name: 'subText', type: 'string', description: 'Set the subtext of radio group', }, { name: 'descriptorsDisplay', type: '"row" | "column"', description: 'Set the orientation of descriptor content located below the radio group', }, ]} /> ``` ```jsx render <Docs.PropsTable of={RadioGroup.Radio} rows={[ { name: 'checked', type: 'boolean', description: 'Flag to see if radio is checked', }, { name: 'children', type: 'ReactNode', description: 'The element the radio wraps', }, { name: 'isDisabled', type: 'boolean', description: 'Flag to see if radio is disabled', }, { name: 'label', type: 'string', description: 'Set the label of radio', }, { name: 'size', type: 'number | string', description: 'Set the size of radio', }, { name: 'sizes', type: 'object', description: 'Dictionary of size keys and their corresponding size value', }, { name: 'value', type: 'string', description: 'Value of the radio', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={RadioGroup} rows={[ { name: 'radio-group-root', description: 'Radio Group root element', }, { name: 'radio-group-label', description: 'Radio Group label', }, { name: 'radio-group-container', description: 'Radio Group container', }, { name: 'radio-group-descriptors', description: 'Radio Group descriptors', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={RadioGroup.Radio} rows={[ { name: 'radio-label', description: 'Label', }, { name: 'radio-button', description: 'Button', }, ]} /> ``` </Tab> <Tab label="Accessibility"> A radio group is a set of checkable buttons, known as radio buttons, where no more than one of the buttons can be checked at a time. Some implementations may initialize the set with all buttons in the unchecked state in order to force the user to check one of the buttons before moving past a certain point in the workflow. The component adheres to standard HTML practices by correctly implementing `<fieldset>`, `<legend>`, and `<input type="radio">` elements. By wrapping the radio buttons within a `<fieldset>` element, the component groups them together, providing semantic structure and an accessible boundary recognized by screen readers. A `<legend>` element is used within the `<fieldset>` to offer a descriptive label, aiding users, especially those utilizing screen readers, in understanding the context of the radio buttons. Each radio button is implemented as an `<input type="radio">` element, ensuring proper behavior and interaction as expected in a web form. #### Differences from common group implementations Required and error reporting are associated with the group `<fieldset>`, not the radio buttons. This is to more clearly associate errors and requirements with the group. Otherwise, unlike `<select>` (which is very similar), one or all of the individual radio buttons might be mistakenly considered "required" or "invalid." Another difference is that though `<legend>` is used to label the grouping, aria-labelledby is also used in `<fieldset>`. This is necessary since, according to HTML standards, `<legend>` must be the first child of `<fieldset>`. Since presentation requires wrapping `<legend>` with `<div>`s, aria-labelledby is used to "patch" the broken relationship and ensure the grouping has an accessible name. For more details on these HTML elements and their usage, please visit the following W3Schools links: - [HTML <fieldset>](https://www.w3schools.com/tags/tag_fieldset.asp) - [HTML <legend>](https://www.w3schools.com/tags/tag_legend.asp) - [HTML <input type="radio">](https://www.w3schools.com/tags/att_input_type_radio.asp) Adheres to the <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/radio/">Radio Group WAI-ARIA design pattern</ExitLink>. ```jsx live () => { const form = useForm({ defaultValues: {}, }); const onSubmit = (data) => { console.log('submitted', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <RadioGroup label="Scoops of ice cream" model="radio-form" subText="Today's flavor is Chocolate" validators={{ required: true }} > <RadioGroup.Radio label="One" value="one" /> <RadioGroup.Radio label="Two" value="two" /> <RadioGroup.Radio label="Three" value="three" /> <RadioGroup.Radio label="Four (maximum)" value="four" /> <RadioGroup.Radio label="None (I don't want any ice cream)" value="none" /> </RadioGroup> <Button type="submit" style={{ marginTop: 15 }}> Submit </Button> </FormProvider> ); }; ``` ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Tab', description: 'Moves focus to either the checked radio item or the first radio item in the group.', }, { name: 'Space', description: 'When focus is on an unchecked radio item, checks it.', }, { name: 'Enter', description: 'When focus is on an unchecked radio item, checks it.', }, { name: 'Arrow Down', description: 'Moves focus to the next radio item in the group.', }, { name: 'Arrow Right', description: 'Moves focus to the next radio item in the group.', }, { name: 'Arrow Up', description: 'Moves focus to the previous radio item in the group.', }, { name: 'Arrow Left', description: 'Moves focus to the previous radio item in the group.', }, ]} /> ``` </Tab> --- id: rating-v2 category: Data Display title: V2Rating description: Used to select and display a rating and reviews. design: https://www.figma.com/design/a8XbEI7AmNb94mOBgYUB7y/v1.73.0-Web-Abyss-Global%E2%80%A8Component-Library?node-id=6561-482&t=ibF5r2mcDlu4v4Lg-0 subDirectory: Rating/v2 sourceIsTS: true --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="Rating"></Docs.V2MigrationBanner> ``` ```jsx import { V2Rating, V2RatingInput } from '@uhg-abyss/web/ui/Rating'; ``` ```jsx sandbox { component: 'V2Rating', inputs: [ { prop: 'rating', type: 'number', maskConfig: { decimalScale: 2, }, }, { prop: 'hideRating', type: 'boolean', }, { prop: 'size', type: 'select', options: [ { label: '$lg', value: '$lg' }, { label: '$sm', value: '$sm' }, ] }, { prop: 'singleStarDisplay', type: 'boolean', }, { prop: 'ratingAriaLabel', type: 'string', }, ] } <V2Rating /> ``` ## Read-only rating ### Rating distribution Use the `distributionConfig` prop to display a rating distribution. This prop accepts an array of objects with type `DistributionConfigItem`, each representing a star rating and its associated percentage. The `href` and `onClick` props can be used to specify a link or button for each star rating. To use one function for all star ratings, use the `onDistributionClick` prop instead. ```ts DistributionConfigItem { starCount: 1 | 2 | 3 | 4 | 5 | number; percentage: number; href?: string; onClick?: ( event: React.MouseEvent<HTMLAnchorElement | HTMLButtonElement> ) => void; } ``` When using a rating distribution, the size of the rating should be set to `$lg` to follow design standards. ```jsx live () => { const distributionConfig = [ { starCount: 5, percentage: 10, onClick: () => { console.log('view 5 star reviews'); }, }, { starCount: 4, percentage: 15, onClick: () => { console.log('view 4 star reviews'); }, }, { starCount: 3, percentage: 25, onClick: () => { console.log('view 3 star reviews'); }, }, { starCount: 2, percentage: 0, onClick: () => { console.log('view 2 star reviews'); }, }, { starCount: 1, percentage: 50, onClick: () => { console.log('view 1 star reviews'); }, }, ]; return ( <V2Rating rating={3} distributionConfig={distributionConfig} reviewsConfig={{ count: 100 }} /> ); }; ``` The rating distribution can be used to filter reviews by star rating. See the example below for one way to implement this functionality. ```jsx live () => { const [filteredRating, setFilteredRating] = useState(null); const reviews = [ { reviewerName: 'Reviewer 1', text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.', rating: 4, }, { reviewerName: 'Reviewer 2', text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.', rating: 3, }, { reviewerName: 'Reviewer 3', text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.', rating: 5, }, { reviewerName: 'Reviewer 4', text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.', rating: 1, }, { reviewerName: 'Reviewer 5', text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.', rating: 1, }, { reviewerName: 'Reviewer 6', text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.', rating: 3, }, { reviewerName: 'Reviewer 7', text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.', rating: 1, }, ]; // Calculate average rating const averageRating = reviews.length > 0 ? Math.round( (reviews.reduce((sum, r) => sum + r.rating, 0) / reviews.length) * 100 ) / 100 : 0; // Calculate percentage for each star value (1-5) const total = reviews.length; const starPercentages = [1, 2, 3, 4, 5].map((star) => { const count = reviews.filter((r) => r.rating === star).length; return total > 0 ? Math.round((count / total) * 100) : 0; }); // Filter reviews by selected rating, or show all if null const getFilteredReviews = (rating) => rating === null ? reviews : reviews.filter((review) => review.rating === rating); // Content to display, filtered by starCount if selected const content = getFilteredReviews(filteredRating).map( (review, index, arr) => ( <React.Fragment key={index}> <Layout.Stack width="100%" alignItems="left" space={0}> <Text fontWeight="bold">{review.reviewerName}</Text> <Text>{review.text}</Text> <V2Rating rating={review.rating} hideReviews hideRating size={'$sm'} headingLevel={0} /> </Layout.Stack> {index < arr.length - 1 && <Divider />} </React.Fragment> ) ); const handleDistributionClick = (starCount) => { setFilteredRating((current) => (current === starCount ? null : starCount)); }; const distributionConfig = [ { starCount: 5, percentage: starPercentages[4], }, { starCount: 4, percentage: starPercentages[3], }, { starCount: 3, percentage: starPercentages[2], }, { starCount: 2, percentage: starPercentages[1], }, { starCount: 1, percentage: starPercentages[0], }, ]; return ( <Layout.Stack width="100%" alignItems="left" space={20}> <V2Rating rating={averageRating} distributionConfig={distributionConfig} reviewsConfig={{ count: reviews.length }} onDistributionClick={handleDistributionClick} /> <Box>{content.length > 0 ? content : <Text>No reviews found.</Text>}</Box> </Layout.Stack> ); }; ``` ### Size and star display Use the `size` prop to specify the size of the component as `$lg`, `$sm`. The default is set to `$lg`. Use the `singleStarDisplay` prop to display a single star instead of the default five stars. ```jsx live <Layout.Stack width="100%" alignItems="left"> <V2Rating rating={2} reviewsConfig={{ count: 15, }} /> <V2Rating rating={2} size="$sm" reviewsConfig={{ count: 15, }} /> <V2Rating rating={2} reviewsConfig={{ count: 15, }} singleStarDisplay /> <V2Rating rating={2} size="$sm" reviewsConfig={{ count: 15, }} singleStarDisplay /> </Layout.Stack> ``` ### Rating Use the `rating` prop to provide the rating value. This value will determine how many of the star icons are active and will be displayed next to the icons by default. To hide the rating number, use the `hideRating` prop. Notes: - If no value is specified, the rating will default to 0. - Decimal numbers are rounded to the nearest half number to determine how many star icons are active. ```jsx live <Layout.Stack width="100%" alignItems="left"> <V2Rating rating={0} hideRating /> <V2Rating /> <V2Rating rating={1} /> <V2Rating rating={2} /> <V2Rating rating={3.56} /> <V2Rating rating={4} /> <V2Rating rating={5} /> </Layout.Stack> ``` ### Reviews configuration To configure the rest of the reviews, use the prop `reviewsConfig`. This prop accepts an object with the following structure: ```ts { count?: number; // Defaults to 0 description?: string; // Defaults to "`count` Reviews" href?: string; onClick?: (event: React.MouseEvent<HTMLAnchorElement | HTMLButtonElement>) => void; } ``` The following sections, [Review description](#review-description) and [Href and onClick](#href-and-onclick) demonstrate how to use each of these properties. ### Review description Use `count` to specify the number of reviews. If no value is specified, the count will default to 0. If the value is less than 0, the review count will display as 0. To not just customize the number, use `description` to customize the text displaying the review count. The default value is "`count` Reviews". Use the separate prop `hideReviews` to hide the review display. ```jsx live <Layout.Stack width="100%" alignItems="left"> <V2Rating rating={4} hideReviews /> <V2Rating rating={4} /> <V2Rating rating={4} reviewsConfig={{ count: 50 }} /> <V2Rating rating={4} reviewsConfig={{ count: 50, description: `There are 50 reviews`, }} singleStarDisplay /> </Layout.Stack> ``` ### Href and onClick Use `href` and `onClick` to turn the review display into either a link or a button styled as a link. ```jsx live () => { const [isModalOpen, setIsModalOpen] = useState(false); const onClick = () => { setIsModalOpen(true); }; const reviews = [ { reviewerName: 'Reviewer 1', text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.', rating: 4, }, { reviewerName: 'Reviewer 2', text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.', rating: 3, }, { reviewerName: 'Reviewer 3', text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.', rating: 5, }, ]; return ( <Layout.Stack width="100%" alignItems="left"> <V2ModalDialog header={'Example Review Modal'} isOpen={isModalOpen} onClose={() => setIsModalOpen(false)} > {reviews.map((review, index) => { return ( <React.Fragment key={index}> <Layout.Stack width="100%" alignItems="left" space={0}> <Text fontWeight="bold">{review.reviewerName}</Text> <Text>{review.text}</Text> <V2Rating rating={review.rating} hideReviews hideRating headingLevel={0} /> </Layout.Stack> {index < reviews.length - 1 && <Divider />} </React.Fragment> ); })} </V2ModalDialog> <V2Rating size="$sm" rating={4} reviewsConfig={{ count: 3, onClick: onClick, }} /> <V2Rating size="$sm" rating={4} reviewsConfig={{ count: 3, description: 'See reviews', href: '#review-link', }} /> <V2Rating size="$sm" rating={4} reviewsConfig={{ count: 3, description: 'Open review modal', onClick: onClick, }} /> </Layout.Stack> ); }; ``` ### Rating ARIA label Use the `ratingAriaLabel` prop to override the default ARIA label for the star count. See the [Accessibility tab](/web/ui/rating-v2?tab=accessibility) for more information regarding the usage of this field. ```jsx live () => { const rating = 3; return ( <V2Rating rating={rating} ratingAriaLabel={`Rating of ${rating} out of 5 stars`} /> ); }; ``` ### Heading level Use the `headingLevel` prop to override the default heading of the Rating. The default is `3`, but it can be set to different values depending on the application's nested heading structure. To display as a `<span>` instead, set it to `0`. ```jsx live () => { return ( <V2Rating rating={4} headingLevel={0} reviewsConfig={{ count: 0, description: '4 star rating', }} /> ); }; ``` ## Interactive rating input For an interactive rating input, use the `V2RatingInput` component. This component is a form input that allows users to select a rating value. This means that properties used by other form inputs can also be applied to this component, such as `validators`, `subtext`, `hideLabel`, and `helper`. Further explanation of such props can be found in the [V2TextInput](/web/ui/text-input-v2#display-properties) documentation. ### useFormV2 (recommended) Using the `useFormV2` hook lets the DOM handle form data when the component is wrapped in the `V2FormProvider`. Note: The default error message when `required` is `true` is minimally acceptable for accessibility. It is highly recommended to customize it to be more specific to the use of the field and form. ```jsx live () => { const form = useFormV2({}); const onSubmit = (data) => { console.log('submitted', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2RatingInput label="V2RatingInput useFormV2" model="rating-form" validators={{ required: true }} size="$sm" helper="This is a required field" subText="How would you rate this experience?" /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ### useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [ratingValue, setRatingValue] = useState('3'); console.log('ratingValue', ratingValue); return ( <V2RatingInput label="V2RatingInput useState" onChange={(e) => setRatingValue(e.target.value)} value={ratingValue} /> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2Rating" propTypeName="V2RatingProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="V2RatingInput" propTypeName="V2RatingInputProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2ClassesTable title="V2Rating" classes={[RatingClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2RatingInput" classes={[RatingInputClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> A Rating is used to display some user-provided rating of an item. Rating is not a focusable component, but is accessible to screen readers. The following examples are fully accessible. ```jsx live () => { const [filteredRating, setFilteredRating] = useState(null); const reviews = [ { reviewerName: 'Obi1', text: 'Jedi represented badly in battle. Lightsabres are not a Jedis only strengh', rating: 4, }, { reviewerName: 'Jaba3Hutt', text: 'Mooji wan yi solo. Ho ho ho Jedi.', rating: 3, }, { reviewerName: 'lOrgana', text: 'A princess should not be subjected to such terrible costumes.', rating: 3, }, { reviewerName: 'Chewie', text: 'Aarrrgggh. Arrh', rating: 4, }, { reviewerName: 'notDroidURLookingFor', text: 'Beep beep boop whooo bzzz', rating: 5, }, { reviewerName: 'dVader', text: 'Baby daddies have a right to visit and raise their children on the dark side.', rating: 3, }, { reviewerName: 'AdmAckbar', text: "It's a trap!", rating: 1, }, ]; // Calculate average rating const averageRating = reviews.length > 0 ? Math.round( (reviews.reduce((sum, r) => sum + r.rating, 0) / reviews.length) * 100 ) / 100 : 0; // Calculate percentage for each star value (1-5) const total = reviews.length; const starPercentages = [1, 2, 3, 4, 5].map((star) => { const count = reviews.filter((r) => r.rating === star).length; return total > 0 ? Math.round((count / total) * 100) : 0; }); // Filter reviews by selected rating, or show all if null const getFilteredReviews = (rating) => rating === null ? reviews : reviews.filter((review) => review.rating === rating); // Content to display, filtered by starCount if selected const content = getFilteredReviews(filteredRating).map( (review, index, arr) => ( <React.Fragment key={index}> <li> <div role="heading" aria-level="4"> <strong>{review.reviewerName}</strong> </div> <p>{review.text}</p> <V2Rating rating={review.rating} hideReviews hideRating headingLevel={0} /> {index < arr.length - 1 && <Divider />} </li> </React.Fragment> ) ); const handleDistributionClick = (starCount) => { setFilteredRating((current) => (current === starCount ? null : starCount)); }; const distributionConfig = [ { starCount: 5, percentage: starPercentages[4], onClick: () => handleDistributionClick(5), }, { starCount: 4, percentage: starPercentages[3], onClick: () => handleDistributionClick(4), }, { starCount: 3, percentage: starPercentages[2], onClick: () => handleDistributionClick(3), }, { starCount: 2, percentage: starPercentages[1], onClick: () => handleDistributionClick(2), }, { starCount: 1, percentage: starPercentages[0], onClick: () => handleDistributionClick(1), }, ]; return ( <Layout.Stack width="100%" alignItems="left" space={20}> <h2>Star Wars: Episode VI - Return of the Jedi</h2> <V2Rating rating={averageRating} distributionConfig={distributionConfig} reviewsConfig={{ count: reviews.length }} /> <Box> <ul aria-label="Matching reviews"> {content.length > 0 ? content : <p>No reviews found.</p>} </ul> </Box> </Layout.Stack> ); }; ``` #### ARIA Labels Since the visible text in a Rating is very succinct, ARIA labels are required in order to provide meaningful descriptions for assistive technologies to read to the user. For example, "3 of 5 stars," or, "Rating of 3 out of 5 stars." The `ratingAriaLabel` prop will override the default value, but it is important to remember that any value provided through this prop should still provide a meaningful description of the rating. In the `single` variant, only one star is visible, meaning that the rating number must absolutely be visible and there must be a descriptive ARIA label to relay the actual rating. Use of the `hideRating` prop is possible, but discouraged. If the rating number is hidden, the rating value is only conveyed through the star icons, which may be problematic for some users. In cases where `hideRating` is used, it is therefore not recommended to override the ARIA label with `ratingAriaLabel` unless that label contains a meaningful description of the rating. ```jsx live () => { const rating = 3; const [isModalOpen, setIsModalOpen] = useState(false); const onClick = () => { setIsModalOpen(true); }; const reviews = [ { reviewerName: 'Reviewer 1', text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.', rating: 4, }, { reviewerName: 'Reviewer 2', text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.', rating: 3, }, { reviewerName: 'Reviewer 3', text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.', rating: 5, }, ]; return ( <Layout.Stack width="100%" alignItems="left"> <V2ModalDialog header={'Sample reviews'} isOpen={isModalOpen} onClose={() => setIsModalOpen(false)} > <ul aria-label="Available reviews"> {reviews.map((review, index) => { return ( <React.Fragment key={index}> <li> <Layout.Stack width="100%" alignItems="left" space={0}> <div role="heading" aria-level="3"> <strong>{review.reviewerName}</strong> </div> <p>{review.text}</p> <V2Rating rating={review.rating} hideReviews hideRating headingLevel={0} /> </Layout.Stack> {index < reviews.length - 1 && <Divider />} </li> </React.Fragment> ); })} </ul> </V2ModalDialog> <h2>ARIA labels</h2> <p> <V2Rating rating={rating} ratingAriaLabel={`Rating of ${rating} out of 5 stars`} reviewsConfig={{ count: 234 }} /> </p> <p> <V2Rating rating={rating} ratingAriaLabel={`Rating of ${rating} out of 5 stars`} singleStarDisplay reviewsConfig={{ count: 5234 }} /> </p> <h2>Hide ratings</h2> <p> <V2Rating rating={4} hideRating reviewsConfig={{ count: 463, description: 'See review (modal)', onClick: onClick, }} /> </p> <p> <V2Rating rating={4} hideRating reviewsConfig={{ count: 212, description: 'See reviews (page)', href: '#review-link', }} /> </p> <p> <V2Rating rating={4} size="$sm" hideRating reviewsConfig={{ count: 82 }} /> </p> <p> <V2Rating rating={4} singleStarDisplay hideRating reviewsConfig={{ count: 792 }} /> </p> </Layout.Stack> ); }; ``` #### Interactive rating input ```jsx live () => { const form = useFormV2({}); const onSubmit = (data) => { console.log('submitted', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <h2>Feedback please...</h2> <V2RatingInput label="How would you rate your experience?" model="rating-form" validators={{ required: true }} size="$sm" helper="We really do want your input to make improvements" subText="Be very honest!" /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={V2Rating} keys={['ratingV2']} /> ``` </Tab> --- id: rating category: Data Display title: Rating description: Used to select and display a rating and reviews. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=36882-120337 subDirectory: Rating/v1 --- <Tab label="Overview"> ```jsx import { Rating } from '@uhg-abyss/web/ui/Rating'; ``` ```jsx sandbox { component: 'Rating', inputs: [ { prop: 'rating', type: 'number', maskConfig: { decimalScale: 2, }, }, { prop: 'hideRating', type: 'boolean', }, { prop: 'reviewCount', type: 'number', }, { prop: 'reviewDescription', type: 'string', }, { prop: 'reviewAction', type: 'string', }, { prop: 'hideReviews', type: 'boolean', }, { prop: 'size', type: 'select', options: [ { label: 'large', value: 'large' }, { label: 'small', value: 'small' }, { label: 'single', value: 'single' }, ] }, { prop: 'ratingAriaLabel', type: 'string', }, ] } () => { return ( <Rating /> ); }; ``` ## Size Use the `size` prop to specify the size of the component as `large`, `small`, or `single`. The default is set to `large`. ```jsx live <Layout.Stack alignItems="left"> <Rating rating={2} /> <Rating rating={2} size="small" /> <Rating rating={2} size="single" /> </Layout.Stack> ``` ## Rating Use the `rating` prop to provide the rating value. This value will determine how many of the star icons are active and will be displayed next to the icons by default. Notes: - If no value is specified, the rating will default to 0. - If the value is less than 0, the rating will display as 0. - If the value is greater than 5, the rating will display as 5. - Decimal numbers will be rounded to the nearest whole number for the numerical display and to determine how many star icons are active. Icons cannot be partially filled. ```jsx live <Layout.Stack alignItems="left"> <Rating /> <Rating rating={-1} /> <Rating rating={1} /> <Rating rating={2} /> <Rating rating={3.56} /> <Rating rating={4} /> <Rating rating={5} /> <Rating rating={6} /> </Layout.Stack> ``` ## Hide rating Use the `hideRating` prop to hide the rating's numerical display. Note that this has no effect if using size `single`. See the [Accessibility tab](/web/ui/rating?tab=accessibility) for more information. ```jsx live <Layout.Stack alignItems="left"> <Rating rating={4} /> <Rating rating={4} hideRating /> <Rating rating={4} size="single" hideRating /> </Layout.Stack> ``` ## Review count Use the `reviewCount` prop to specify the number of reviews. If no value is specified, the count will default to 0. If the value is less than 0, the review count will display as 0. ```jsx live <Layout.Stack alignItems="left"> <Rating rating={4} /> <Rating rating={4} reviewCount={50} /> <Rating rating={4} reviewCount={50} size="single" /> </Layout.Stack> ``` ## Review description Use the `reviewDescription` prop to customize the text displaying the review count. The default value is "`reviewCount` Reviews". ```jsx live () => { const reviewCount = 13; return ( <Layout.Stack alignItems="left"> <Rating rating={4} reviewCount={reviewCount} /> <Rating rating={4} reviewCount={reviewCount} reviewDescription={`There are ${reviewCount} reviews`} /> <Rating rating={4} reviewCount={reviewCount} size="single" reviewDescription={`There are ${reviewCount} reviews`} /> </Layout.Stack> ); }; ``` ## Review action Use the `reviewAction` prop to turn the review display into either a link or a button styled as a link. This accepts either a string or a callback function. If a string is given, it is treated as an href and the review text will be converted to a link. If a function is provided, the review text will be rendered as a button styled as a link, and will be executed when the button is clicked. ```jsx live () => { const [isModalOpen, setIsModalOpen] = useState(false); const onClick = () => { setIsModalOpen(true); }; const reviews = [ { reviewerName: 'Reviewer 1', text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.', rating: 4, }, { reviewerName: 'Reviewer 2', text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.', rating: 3, }, { reviewerName: 'Reviewer 3', text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.', rating: 5, }, ]; return ( <Layout.Stack alignItems="left"> <Modal title="Example Review Modal" isOpen={isModalOpen} onClose={() => setIsModalOpen(false)} > <Modal.Section> {reviews.map((review, index) => { return ( <React.Fragment key={index}> <Layout.Stack alignItems="left" space={0}> <Text fontWeight="bold">{review.reviewerName}</Text> <Text>{review.text}</Text> <Rating size="large" rating={review.rating} hideReviews hideRating /> </Layout.Stack> {index < reviews.length - 1 && <Divider />} </React.Fragment> ); })} </Modal.Section> </Modal> <Rating rating={4} reviewCount={3} reviewDescription="See reviews" reviewAction="#review-link" /> <Rating rating={4} reviewCount={3} reviewDescription="See reviews" reviewAction={`${window.location.origin}/web/ui/rating/#review-link`} /> <Rating rating={4} reviewCount={3} reviewDescription="Open review modal" reviewAction={onClick} /> <Rating rating={4} size="single" reviewCount={3} reviewDescription="Open review modal" reviewAction={onClick} /> </Layout.Stack> ); }; ``` ## Hide reviews Use the `hideReviews` prop to hide the review display. ```jsx live <Layout.Stack alignItems="left"> <Rating rating={4} /> <Rating rating={4} hideReviews /> <Rating rating={4} size="single" hideReviews /> </Layout.Stack> ``` ## Rating ARIA label Use the `ratingAriaLabel` prop to override the default ARIA label for the star count, which is "`rating` of 5 stars" for the `large` and `small` variants, and "`rating` stars" for the `single` variant. See the [Accessibility tab](/web/ui/rating?tab=accessibility) for more information regarding the usage of this field. ```jsx live () => { const rating = 3; return ( <Rating rating={rating} ratingAriaLabel={`Rating of ${rating} out of 5 stars`} /> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={Rating} rows={[ { name: 'rating', type: 'number', description: 'Rating number', }, { name: 'hideRating', type: 'boolean', description: 'Hides rating number', }, { name: 'reviewCount', type: 'number', description: 'Number of reviews', }, { name: 'reviewDescription', type: 'string', description: 'Specifies how the review text will be formatted', }, { name: 'reviewAction', type: 'string | function', description: 'Specifies the behavior of the review display text; either a string representing an href or a function to execute on click', }, { name: 'hideReviews', type: 'boolean', description: 'Hides review text', }, { name: 'size', type: '"large" | "small" | "single"', description: 'Defines the size of the component', }, { name: 'ratingAriaLabel', type: 'string', description: 'Overrides the default ARIA label for the rating; more details available on the Accessibility tab', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Rating} rows={[ { name: 'rating-root', description: 'Rating root', }, { name: 'rating-stars-container', description: 'Container wrapping the stars', }, { name: 'rating-star', description: 'Each individual star', }, { name: 'rating-text', description: 'The text/link to the right of the stars', }, ]} /> ``` </Tab> <Tab label="Accessibility"> A Rating is used to display some user-provided rating of an item. Rating is not a focusable component, but is accessible to screen readers. #### ARIA Labels Since the visible text in a Rating is very succinct, ARIA labels are required in order to provide meaningful descriptions for assistive technologies to read to the user. For example, "3 of 5 stars," or, "Rating of 3 out of 5 stars." The `ratingAriaLabel` prop will override the default value, but it is important to remember that any value provided through this prop should still provide a meaningful description of the rating. In the `single` variant, only one star is visible, meaning that the rating number must absolutely be visible and there must be a descriptive ARIA label to relay the actual rating. ```jsx live () => { const rating = 3; return ( <Layout.Stack alignItems="left"> <Rating rating={rating} ratingAriaLabel={`Rating of ${rating} out of 5 stars`} /> <Rating rating={rating} ratingAriaLabel={`Rating of ${rating} out of 5 stars`} size="single" /> </Layout.Stack> ); }; ``` #### Hide Rating Use of the `hideRating` prop is possible, but discouraged. If the rating number is hidden, the rating value is only conveyed through the star icons, which may be problematic for some users. Because of this, `hideRating` has no effect on the `single` variant, as there would otherwise be no way to convey the rating value. In cases where `hideRating` is used, it is therefore not recommended to override the ARIA label with `ratingAriaLabel` unless that label contains a meaningful description of the rating. ```jsx live <Layout.Stack alignItems="left"> <Rating rating={4} /> <Rating rating={4} hideRating /> <Rating rating={4} size="small" hideRating /> <Rating rating={4} size="single" hideRating /> </Layout.Stack> ``` </Tab> --- id: rich-text-editor-v2 category: Forms title: V2RichTextEditor description: Component for generating rich text. design: https://www.figma.com/design/a8XbEI7AmNb94mOBgYUB7y/v1.75.0-Web-Abyss-Global%E2%80%A8Component-Library?node-id=10461-2241&p=f&m=dev subDirectory: RichTextEditor/v2 sourceIsTS: true --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="RichTextEditor"></Docs.V2MigrationBanner> ``` ```jsx import { V2RichTextEditor } from '@abyss/web/ui/RichTextEditor'; ``` ## Overview `V2RichTextEditor` is a rich text editor component built using [tiptap](https://tiptap.dev/docs). It provides a user-friendly interface for creating and editing rich text content with various formatting options. ```jsx live () => { const form = useFormV2({ defaultValues: { usage: '<p>Rich Text Editor</p>', }, }); return ( <V2FormProvider state={form}> <V2RichTextEditor model="usage" label="Rich Text Editor" format="html"> <V2RichTextEditor.Toolbar> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Undo /> <V2RichTextEditor.Redo /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Bold /> <V2RichTextEditor.Italic /> <V2RichTextEditor.Underline /> <V2RichTextEditor.Strike /> <V2RichTextEditor.Color /> <V2RichTextEditor.BackgroundColor /> <V2RichTextEditor.Highlight /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Headings /> <V2RichTextEditor.FontSize /> <V2RichTextEditor.Alignments /> <V2RichTextEditor.Lists /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Image /> <V2RichTextEditor.Copy /> <V2RichTextEditor.Link /> <V2RichTextEditor.Code /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Table /> <V2RichTextEditor.TableRows /> <V2RichTextEditor.TableColumns /> </V2RichTextEditor.ControlsGroup> </V2RichTextEditor.Toolbar> </V2RichTextEditor> </V2FormProvider> ); }; ``` ## Usage Use sub-components of `V2RichTextEditor` to build a toolbar of options for editing text. Controls should be placed within the `<V2RichTextEditor.Toolbar>` component and grouped by the `<V2RichTextEditor.ControlsGroup>` component. - Undo or Redo actions with - `<V2RichTextEditor.Undo />` - `<V2RichTextEditor.Redo />` - Format text styles with - `<V2RichTextEditor.Bold />` - `<V2RichTextEditor.Italic />` - `<V2RichTextEditor.Underline />` - `<V2RichTextEditor.Strike />` - `<V2RichTextEditor.Color />` - `<V2RichTextEditor.BackgroundColor />` - `<V2RichTextEditor.Highlight />` - Edit text with - `<V2RichTextEditor.Headings />` - `<V2RichTextEditor.FontSize />` - `<V2RichTextEditor.Alignments />` - `<V2RichTextEditor.Lists />` - Add/Copy elements with - `<V2RichTextEditor.Link />` - `<V2RichTextEditor.Code />` - `<V2RichTextEditor.Image />` - `<V2RichTextEditor.Copy />` - Add tables with - `<V2RichTextEditor.Table />` - `<V2RichTextEditor.TableRows />` - `<V2RichTextEditor.TableColumns />` - Separate groups with - `<V2RichTextEditor.Separator />` ## Customization You can customize the toolbar by adding or removing controls as needed. Some controls have additional props for further customization: - `<V2RichTextEditor.FontSize />` - Customize available font sizes using the `fontSizes` prop. - `<V2RichTextEditor.Color />` - Customize available colors using the `colors` prop. - `V2RichTextEditor.BackgroundColor` - Customize available background colors using the `backgroundColors` prop. - `V2RichTextEditor.Table` - Customize the default table configuration using the `tableConfig` prop. ```jsx live () => { const form = useFormV2({ defaultValues: { 'rich-text-editor': "<p>Try changing this text's styling with the controls above or insert a table below</p>", }, }); return ( <V2FormProvider state={form}> <V2RichTextEditor label="Customization" format="html" model="rich-text-editor" > <V2RichTextEditor.Toolbar> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Undo /> <V2RichTextEditor.Redo /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Color colors={[ { code: '#FF5733', label: 'Orange' }, { code: '#C70039', label: 'Red' }, { code: '#900C3F', label: 'Magenta' }, { code: '#581845', label: 'Purple' }, ]} /> <V2RichTextEditor.BackgroundColor backgroundColors={[ { code: '#FFCDD2', label: 'Light Red' }, { code: '#C8E6C9', label: 'Light Green' }, { code: '#BBDEFB', label: 'Light Blue' }, { code: '#FFF9C4', label: 'Light Yellow' }, ]} /> <V2RichTextEditor.FontSize fontSizes={['12px', '16px', '20px', '24px', '32px']} /> <V2RichTextEditor.Separator /> <V2RichTextEditor.Table tableConfig={{ rows: 4, cols: 8, withHeaderRow: true }} /> </V2RichTextEditor.ControlsGroup> </V2RichTextEditor.Toolbar> </V2RichTextEditor> </V2FormProvider> ); }; ``` ## useForm (recommended) ```jsx live () => { const form = useFormV2({ defaultValues: { 'rich-text-editor': '<p>text</p>', }, }); return ( <V2FormProvider state={form}> <V2RichTextEditor label="useForm" format="html" model="rich-text-editor"> <V2RichTextEditor.Toolbar> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Undo /> <V2RichTextEditor.Redo /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Bold /> <V2RichTextEditor.Italic /> <V2RichTextEditor.Underline /> <V2RichTextEditor.Strike /> <V2RichTextEditor.Color /> <V2RichTextEditor.BackgroundColor /> <V2RichTextEditor.Highlight /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Headings /> <V2RichTextEditor.FontSize /> <V2RichTextEditor.Alignments /> <V2RichTextEditor.Lists /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Image /> <V2RichTextEditor.Copy /> <V2RichTextEditor.Link /> <V2RichTextEditor.Code /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Table /> <V2RichTextEditor.TableRows /> <V2RichTextEditor.TableColumns /> </V2RichTextEditor.ControlsGroup> </V2RichTextEditor.Toolbar> </V2RichTextEditor> <V2Button css={{ marginTop: '$md' }} onClick={() => { console.log(form.getValues()); }} > Submit </V2Button> </V2FormProvider> ); }; ``` ## useState ```jsx live () => { const [value, setValue] = useState('<p>text</p>'); return ( <> <V2RichTextEditor onChange={(e) => { setValue(e); }} value={value} label="useState" format="html" > <V2RichTextEditor.Toolbar> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Undo /> <V2RichTextEditor.Redo /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Bold /> <V2RichTextEditor.Italic /> <V2RichTextEditor.Underline /> <V2RichTextEditor.Strike /> <V2RichTextEditor.Color /> <V2RichTextEditor.BackgroundColor /> <V2RichTextEditor.Highlight /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Headings /> <V2RichTextEditor.FontSize /> <V2RichTextEditor.Alignments /> <V2RichTextEditor.Lists /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Image /> <V2RichTextEditor.Copy /> <V2RichTextEditor.Link /> <V2RichTextEditor.Code /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Table /> <V2RichTextEditor.TableRows /> <V2RichTextEditor.TableColumns /> </V2RichTextEditor.ControlsGroup> </V2RichTextEditor.Toolbar> </V2RichTextEditor> <V2Button css={{ marginTop: '$md' }} onClick={() => { console.log(value); }} > Submit </V2Button> </> ); }; ``` ## Disabling options Manually disable certain options by using the `isDisabled` prop. ```jsx live () => { const [value, setValue] = useState('<p>text</p>'); return ( <V2RichTextEditor onChange={(e) => { setValue(e); }} value={value} label="Disabled Options" format="html" > <V2RichTextEditor.Toolbar> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Undo isDisabled /> <V2RichTextEditor.Redo isDisabled /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Bold isDisabled /> <V2RichTextEditor.Italic isDisabled /> <V2RichTextEditor.Underline isDisabled /> <V2RichTextEditor.Strike isDisabled /> <V2RichTextEditor.Color isDisabled /> <V2RichTextEditor.BackgroundColor isDisabled /> <V2RichTextEditor.Highlight isDisabled /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Headings isDisabled /> <V2RichTextEditor.FontSize isDisabled /> <V2RichTextEditor.Alignments isDisabled /> <V2RichTextEditor.Lists isDisabled /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Image isDisabled /> <V2RichTextEditor.Copy isDisabled /> <V2RichTextEditor.Link isDisabled /> <V2RichTextEditor.Code isDisabled /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Table isDisabled /> <V2RichTextEditor.TableRows isDisabled /> <V2RichTextEditor.TableColumns isDisabled /> </V2RichTextEditor.ControlsGroup> </V2RichTextEditor.Toolbar> </V2RichTextEditor> ); }; ``` ## Format - HTML/JSON Change the output format to JSON by passing the string `'json'` to the `format` prop. ```jsx live () => { const form = useFormV2({ defaultValues: { 'rich-text-editor': '<p>text</p>', }, }); return ( <V2FormProvider state={form}> <V2RichTextEditor label="Format" format="json" model="rich-text-editor"> <V2RichTextEditor.Toolbar> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Undo /> <V2RichTextEditor.Redo /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Bold /> <V2RichTextEditor.Italic /> <V2RichTextEditor.Underline /> <V2RichTextEditor.Strike /> <V2RichTextEditor.Color /> <V2RichTextEditor.BackgroundColor /> <V2RichTextEditor.Highlight /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Headings /> <V2RichTextEditor.FontSize /> <V2RichTextEditor.Alignments /> <V2RichTextEditor.Lists /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Image /> <V2RichTextEditor.Copy /> <V2RichTextEditor.Link /> <V2RichTextEditor.Code /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Table /> <V2RichTextEditor.TableRows /> <V2RichTextEditor.TableColumns /> </V2RichTextEditor.ControlsGroup> </V2RichTextEditor.Toolbar> </V2RichTextEditor> <V2Button css={{ marginTop: '$md' }} onClick={() => { console.log(form.getValues()); }} > Submit </V2Button> </V2FormProvider> ); }; ``` ## Ref Use the `ref` prop to pass in a ref to the component. `V2RichTextEditor` will then attach the `updateContent` function to this ref, which can be called to programmatically update the content of the editor. Note that the `updateContent` function will not make changes if the new content is identical to the previous content. ```jsx live () => { const editorRef = useRef(null); const form = useFormV2({ defaultValues: { 'rich-text-editor': '<p>text</p>', }, }); const handleUpdate = () => { editorRef.current?.updateContent( '<p>Updated content inside the editor using ref</p>' ); }; return ( <V2FormProvider state={form}> <V2RichTextEditor label="useForm" format="html" model="rich-text-editor" ref={editorRef} > <V2RichTextEditor.Toolbar> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Undo /> <V2RichTextEditor.Redo /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Bold /> <V2RichTextEditor.Italic /> <V2RichTextEditor.Underline /> <V2RichTextEditor.Strike /> <V2RichTextEditor.Color /> <V2RichTextEditor.BackgroundColor /> <V2RichTextEditor.Highlight /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Headings /> <V2RichTextEditor.FontSize /> <V2RichTextEditor.Alignments /> <V2RichTextEditor.Lists /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Image /> <V2RichTextEditor.Copy /> <V2RichTextEditor.Link /> <V2RichTextEditor.Code /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Table /> <V2RichTextEditor.TableRows /> <V2RichTextEditor.TableColumns /> </V2RichTextEditor.ControlsGroup> </V2RichTextEditor.Toolbar> </V2RichTextEditor> <Layout.Group css={{ marginTop: '$md' }}> <V2Button onClick={handleUpdate}>Update Content</V2Button> <V2Button onClick={() => { console.log(form.getValues()); }} > Submit </V2Button> </Layout.Group> </V2FormProvider> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2RichTextEditor.Alignments" propTypeName="V2AlignmentsProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="V2RichTextEditor.BackgroundColor" propTypeName="V2BackgroundColorProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="V2RichTextEditor.Bold" propTypeName="V2BoldProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="V2RichTextEditor.Color" propTypeName="V2ColorProps" showAbyssDefaultTypes /> ``` ````jsx render <Docs.V2WebPropsTable title="V2RichTextEditor.Copy" propTypeName="V2CopyProps" showAbyssDefaultTypes /> ```jsx render <Docs.V2WebPropsTable title="V2RichTextEditor.FontSize" propTypeName="V2FontSizeProps" showAbyssDefaultTypes /> ```` ```jsx render <Docs.V2WebPropsTable title="V2RichTextEditor.Headings" propTypeName="V2HeadingsProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="V2RichTextEditor.Highlight" propTypeName="V2HighlightProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="V2RichTextEditor.Image" propTypeName="V2ImageProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="V2RichTextEditor.Italic" propTypeName="V2ItalicProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="V2RichTextEditor.Link" propTypeName="V2LinkProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="V2RichTextEditor.Lists" propTypeName="V2ListsProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="V2RichTextEditor.Redo" propTypeName="V2RedoProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="V2RichTextEditor.Strike" propTypeName="V2StrikeProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="V2RichTextEditor.Table" propTypeName="V2TableProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="V2RichTextEditor.TableColumns" propTypeName="V2TableColumnsProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="V2RichTextEditor.TableRows" propTypeName="V2TableRowsProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="V2RichTextEditor.Toolbar" propTypeName="V2ToolbarProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="V2RichTextEditor.Underline" propTypeName="V2UnderlineProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="V2RichTextEditor.Undo" propTypeName="V2UndoProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="V2RichTextEditor" propTypeName="V2RichTextEditorProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2ClassesTable title="V2RichTextEditor" classes={[V2RichTextEditorClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2RichTextEditor.ControlsButton" classes={[V2ControlsButtonClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2RichTextEditor.ControlsGroup" classes={[V2ControlsGroupClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2RichTextEditor.ControlsDropdown" classes={[V2ControlsDropdownClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2RichTextEditor.Alignments" classes={[V2AligmentsClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2RichTextEditor.BackgroundColor" classes={[V2BackgroundColorClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2RichTextEditor.Bold" classes={[V2BoldClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2RichTextEditor.Color" classes={[V2ColorClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2RichTextEditor.Copy" classes={[V2CopyClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2RichTextEditor.FontSize" classes={[V2FontSizeClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2RichTextEditor.Headings" classes={[V2HeadingsClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2RichTextEditor.Highlight" classes={[V2HighlightClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2RichTextEditor.Image" classes={[V2ImageClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2RichTextEditor.Italic" classes={[V2ItalicClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2RichTextEditor.Link" classes={[V2LinkClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2RichTextEditor.Lists" classes={[V2ListsClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2RichTextEditor.Redo" classes={[V2RedoClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2RichTextEditor.Separator" classes={[V2SeparatorClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2RichTextEditor.Strike" classes={[V2StrikeClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2RichTextEditor.Table" classes={[V2TableClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2RichTextEditor.TableColumns" classes={[V2TableColumnsClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2RichTextEditor.TableRows" classes={[V2TableRowsClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2RichTextEditor.Toolbar" classes={[V2ToolbarClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2RichTextEditor.Underline" classes={[V2UnderlineClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2RichTextEditor.Undo" classes={[V2UndoClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> ```jsx live () => { const form = useFormV2({ defaultValues: { 'rich-text-editor': '<h1>Welcome!</h1> <p>This is the V2RichText Editor. With it you can create a document with <b>robust</b> styles and a variety of features, including links and tables.</p>', }, }); return ( <V2FormProvider state={form}> <V2RichTextEditor label="Web Word Processor" format="html" model="rich-text-editor" > <V2RichTextEditor.Toolbar> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Undo /> <V2RichTextEditor.Redo /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Bold /> <V2RichTextEditor.Italic /> <V2RichTextEditor.Underline /> <V2RichTextEditor.Strike /> <V2RichTextEditor.Color /> <V2RichTextEditor.BackgroundColor /> <V2RichTextEditor.Highlight /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Headings /> <V2RichTextEditor.FontSize /> <V2RichTextEditor.Alignments /> <V2RichTextEditor.Lists /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Image /> <V2RichTextEditor.Copy /> <V2RichTextEditor.Link /> <V2RichTextEditor.Code /> <V2RichTextEditor.Separator /> </V2RichTextEditor.ControlsGroup> <V2RichTextEditor.ControlsGroup> <V2RichTextEditor.Table /> <V2RichTextEditor.TableRows /> <V2RichTextEditor.TableColumns /> </V2RichTextEditor.ControlsGroup> </V2RichTextEditor.Toolbar> </V2RichTextEditor> <V2Button css={{ marginTop: '$md' }} onClick={() => { console.log(form.getValues()); }} > Submit </V2Button> </V2FormProvider> ); }; ``` ```jsx render <Docs.AccessibilityTable title="Rich Text Editor" rows={[ { name: 'Control + Z', description: 'Undo', }, { name: 'Control + Shift + Z', description: 'Redo', }, { name: 'Control + B', description: 'Bold', }, { name: 'Control + I', description: 'Italic', }, { name: 'Control + U', description: 'Underline', }, { name: 'Control + Shift + S', description: 'Strikethrough', }, { name: 'Control + Shift + H', description: 'Highlight', }, { name: 'Control + E', description: 'Code', }, { name: 'Control + Shift + 7', description: 'Ordered list', }, { name: 'Control + Shift + 8', description: 'Bullet list', }, { name: 'Control + Shift + L', description: 'Left Align', }, { name: 'Control + Shift + E', description: 'Center Align', }, { name: 'Control + Shift + R', description: 'Right Align', }, { name: 'Control + Shift + J', description: 'Justify', }, { name: 'Control + Alt + 0', description: 'Normal Text', }, { name: 'Control + Alt + 1', description: 'Heading 1', }, { name: 'Control + Alt + 2', description: 'Heading 2', }, { name: 'Control + Alt + 3', description: 'Heading 3', }, { name: 'Control + Alt + 4', description: 'Heading 4', }, { name: 'Control + Alt + 5', description: 'Heading 5', }, { name: 'Control + Alt + 6', description: 'Heading 6', }, ]} /> ``` ```jsx render <Docs.AccessibilityTable title="Navigating Inside Toolbar" rows={[ { name: 'Right Arrow', description: 'Moves focus one cell to the right.', }, { name: 'Left Arrow', description: 'Moves focus one cell to the left.', }, { name: 'Enter', description: 'Select Item', }, ]} /> ``` </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={V2RichTextEditor} keys={['richTextEditorV2']} /> ``` </Tab> --- id: rich-text-editor category: Forms title: RichTextEditor description: Component for generating rich text. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=41648-123157 subDirectory: RichTextEditor/v1 --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="RichTextEditor"></Docs.V2MigrationBanner> ``` ```jsx import { RichTextEditor } from '@uhg-abyss/web/ui/RichTextEditor'; ``` ## Usage Use sub-components of `RichTextEditor` to build a toolbar of options for editing text. Controls should be placed within the `<RichTextEditor.Toolbar>` component and grouped by the `<RichTextEditor.ControlsGroup>` component. - Undo or Redo actions with `<RichTextEditor.Undo>`, `<RichTextEditor.Redo>` - Change text styles with `<RichTextEditor.Bold>`, `<RichTextEditor.Italic>`, and `<RichTextEditor.Underline>` - Create lists with `<RichTextEditor.Lists>` - Create Headings with `<RichTextEditor.Headings>` - Change alignments with `<RichTextEditor.Alignments>` - Add links with `<RichTextEditor.Link>` - Add code blocks with `<RichTextEditor.Code>` ```jsx live () => { const form = useForm({ defaultValues: { usage: '<p>Rich Text Editor</p>', }, }); return ( <FormProvider state={form}> <RichTextEditor model="usage" label="Rich Text Editor" format="html"> <RichTextEditor.Toolbar> <RichTextEditor.ControlsGroup> <RichTextEditor.Undo /> <RichTextEditor.Redo /> </RichTextEditor.ControlsGroup> <RichTextEditor.ControlsGroup> <RichTextEditor.Bold /> <RichTextEditor.Italic /> <RichTextEditor.Underline /> </RichTextEditor.ControlsGroup> <RichTextEditor.ControlsGroup> <RichTextEditor.Lists /> <RichTextEditor.Headings /> <RichTextEditor.Alignments /> </RichTextEditor.ControlsGroup> <RichTextEditor.ControlsGroup> <RichTextEditor.Link /> <RichTextEditor.Code /> </RichTextEditor.ControlsGroup> </RichTextEditor.Toolbar> </RichTextEditor> </FormProvider> ); }; ``` ## useForm (recommended) ```jsx live () => { const form = useForm({ defaultValues: { 'rich-text-editor': '<p>text</p>', }, }); return ( <FormProvider state={form}> <RichTextEditor label="useForm" format="html" model="rich-text-editor"> <RichTextEditor.Toolbar> <RichTextEditor.ControlsGroup> <RichTextEditor.Undo /> <RichTextEditor.Redo /> </RichTextEditor.ControlsGroup> <RichTextEditor.ControlsGroup> <RichTextEditor.Bold /> <RichTextEditor.Italic /> <RichTextEditor.Underline /> </RichTextEditor.ControlsGroup> <RichTextEditor.ControlsGroup> <RichTextEditor.Lists /> <RichTextEditor.Headings /> <RichTextEditor.Alignments /> </RichTextEditor.ControlsGroup> <RichTextEditor.ControlsGroup> <RichTextEditor.Link /> <RichTextEditor.Code /> </RichTextEditor.ControlsGroup> </RichTextEditor.Toolbar> </RichTextEditor> <Button css={{ marginTop: '$md' }} onClick={() => { console.log(form.getValues()); }} > Submit </Button> </FormProvider> ); }; ``` ## useState ```jsx live () => { const [value, setValue] = useState('<p>text</p>'); return ( <> <RichTextEditor onChange={(e) => { setValue(e); }} value={value} label="useState" format="html" > <RichTextEditor.Toolbar> <RichTextEditor.ControlsGroup> <RichTextEditor.Undo /> <RichTextEditor.Redo /> </RichTextEditor.ControlsGroup> <RichTextEditor.ControlsGroup> <RichTextEditor.Bold /> <RichTextEditor.Italic /> <RichTextEditor.Underline /> </RichTextEditor.ControlsGroup> <RichTextEditor.ControlsGroup> <RichTextEditor.Lists /> <RichTextEditor.Headings /> <RichTextEditor.Alignments /> </RichTextEditor.ControlsGroup> <RichTextEditor.ControlsGroup> <RichTextEditor.Link /> <RichTextEditor.Code /> </RichTextEditor.ControlsGroup> </RichTextEditor.Toolbar> </RichTextEditor> <Button css={{ marginTop: '$md' }} onClick={() => { console.log(value); }} > Submit </Button> </> ); }; ``` ## Disabling options Manually disable certain options by using the `isDisabled` prop. ```jsx live () => { const [value, setValue] = useState('<p>text</p>'); return ( <RichTextEditor onChange={(e) => { setValue(e); }} value={value} label="Disabled Options" format="html" > <RichTextEditor.Toolbar> <RichTextEditor.ControlsGroup> <RichTextEditor.Undo isDisabled /> <RichTextEditor.Redo isDisabled /> </RichTextEditor.ControlsGroup> <RichTextEditor.ControlsGroup> <RichTextEditor.Bold isDisabled /> <RichTextEditor.Italic isDisabled /> <RichTextEditor.Underline isDisabled /> </RichTextEditor.ControlsGroup> <RichTextEditor.ControlsGroup> <RichTextEditor.Lists isDisabled /> <RichTextEditor.Headings isDisabled /> <RichTextEditor.Alignments isDisabled /> </RichTextEditor.ControlsGroup> <RichTextEditor.ControlsGroup> <RichTextEditor.Link isDisabled /> <RichTextEditor.Code isDisabled /> </RichTextEditor.ControlsGroup> </RichTextEditor.Toolbar> </RichTextEditor> ); }; ``` ## Format - HTML/JSON Change the output format to JSON by passing the string `'json'` to the `format` prop. ```jsx live () => { const form = useForm({ defaultValues: { 'rich-text-editor': '<p>text</p>', }, }); return ( <FormProvider state={form}> <RichTextEditor label="Format" format="json" model="rich-text-editor"> <RichTextEditor.Toolbar> <RichTextEditor.ControlsGroup> <RichTextEditor.Undo /> <RichTextEditor.Redo /> </RichTextEditor.ControlsGroup> <RichTextEditor.ControlsGroup> <RichTextEditor.Bold /> <RichTextEditor.Italic /> <RichTextEditor.Underline /> </RichTextEditor.ControlsGroup> <RichTextEditor.ControlsGroup> <RichTextEditor.Lists /> <RichTextEditor.Headings /> <RichTextEditor.Alignments /> </RichTextEditor.ControlsGroup> <RichTextEditor.ControlsGroup> <RichTextEditor.Link /> <RichTextEditor.Code /> </RichTextEditor.ControlsGroup> </RichTextEditor.Toolbar> </RichTextEditor> <Button css={{ marginTop: '$md' }} onClick={() => { console.log(form.getValues()); }} > Submit </Button> </FormProvider> ); }; ``` ## Ref Use the `ref` prop to pass in a ref to the component. `RichTextEditor` will then attach the `updateContent` function to this ref, which can be called to programmatically update the content of the editor. Note that the `updateContent` function will not make changes if the new content is identical to the previous content. ```jsx live () => { const ref = useRef(null); const form = useForm({ defaultValues: { 'rich-text-editor': '<p>text</p>', }, }); const handleUpdate = () => { ref.updateContent('<p>Updated text</p>'); }; return ( <FormProvider state={form}> <RichTextEditor label="useForm" format="html" model="rich-text-editor" ref={ref} > <RichTextEditor.Toolbar> <RichTextEditor.ControlsGroup> <RichTextEditor.Undo /> <RichTextEditor.Redo /> </RichTextEditor.ControlsGroup> <RichTextEditor.ControlsGroup> <RichTextEditor.Bold /> <RichTextEditor.Italic /> <RichTextEditor.Underline /> </RichTextEditor.ControlsGroup> <RichTextEditor.ControlsGroup> <RichTextEditor.Lists /> <RichTextEditor.Headings /> <RichTextEditor.Alignments /> </RichTextEditor.ControlsGroup> <RichTextEditor.ControlsGroup> <RichTextEditor.Link /> <RichTextEditor.Code /> </RichTextEditor.ControlsGroup> </RichTextEditor.Toolbar> </RichTextEditor> <Layout.Group css={{ marginTop: '$md' }}> <Button onClick={handleUpdate}>Update Content</Button> <Button onClick={() => { console.log(form.getValues()); }} > Submit </Button> </Layout.Group> </FormProvider> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={RichTextEditor} rows={[ { name: 'children', type: 'React.ReactNode', description: 'Rich Text Editor children', }, { name: 'label', type: 'string', description: 'Rich Text Editor label', }, { name: 'value', type: 'string', description: 'Value of the Rich Text Editor', }, { name: 'onChange', type: 'function', description: 'Callback fired every time the value changes', }, { name: 'model', type: 'string', description: 'Form model to be used with FormProvider', }, { name: 'format', type: "'html' | 'json'", description: 'Return html or json data', }, { name: 'hideLabel', type: 'boolean', description: 'Flag to show or hide label', }, { name: 'height', type: 'boolean', description: 'Rich Text Editor height', }, { name: 'ref', type: 'object', description: "Ref to the RichTextEditor. Exposes the 'updateContent' function.", }, ]} /> ``` ```jsx render <Docs.ClassesTable of={RichTextEditor} rows={[ { name: 'rich-text-editor-root', description: 'root container', }, { name: 'rich-text-editor-header', description: 'editor label', }, { name: 'rich-text-editor-content-container', description: 'editor content container', }, { name: 'rich-text-editor-tool-bar', description: 'editor toolbar', }, { name: 'rich-text-editor-controls-group', description: 'editor controls group', }, { name: 'rich-text-editor-controls-button', description: 'editor controls button', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={RichTextEditor.Toolbar} rows={[ { name: 'rich-text-editor-toolbar', description: 'Toolbar root', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={RichTextEditor.ControlsGroup} rows={[ { name: 'rich-text-editor-controls-group', description: 'Control group root', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={RichTextEditor.Undo} rows={[ { name: 'rich-text-editor-controls-button-undo', description: 'Undo button root', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={RichTextEditor.Redo} rows={[ { name: 'rich-text-editor-controls-button-redo', description: 'Redo button root', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={RichTextEditor.Bold} rows={[ { name: 'rich-text-editor-controls-button-bold', description: 'Bold button root', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={RichTextEditor.Italic} rows={[ { name: 'rich-text-editor-controls-button-italic', description: 'Italic button root', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={RichTextEditor.Underline} rows={[ { name: 'rich-text-editor-controls-button-underline', description: 'Underline button root', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={RichTextEditor.Lists} rows={[ { name: 'rich-text-editor-controls-dropdown-lists', description: 'Lists dropdown root', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={RichTextEditor.Headings} rows={[ { name: 'rich-text-editor-controls-dropdown-headings', description: 'Headings dropdown root', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={RichTextEditor.Alignments} rows={[ { name: 'rich-text-editor-controls-dropdown-alignments', description: 'Alignments dropdown root', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={RichTextEditor.Link} rows={[ { name: 'rich-text-editor-controls-button-link', description: 'Link button root', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={RichTextEditor.Code} rows={[ { name: 'rich-text-editor-controls-button-code', description: 'Code button root', }, ]} /> ``` </Tab> <Tab label="Accessibility"> ```jsx live () => { const form = useForm({ defaultValues: { usage: '<p>Accessibility Testing</p>', }, }); return ( <FormProvider state={form}> <RichTextEditor model="usage" label="Rich Text Editor" format="html"> <RichTextEditor.Toolbar> <RichTextEditor.ControlsGroup> <RichTextEditor.Undo /> <RichTextEditor.Redo /> </RichTextEditor.ControlsGroup> <RichTextEditor.ControlsGroup> <RichTextEditor.Bold /> <RichTextEditor.Italic /> <RichTextEditor.Underline /> </RichTextEditor.ControlsGroup> <RichTextEditor.ControlsGroup> <RichTextEditor.Lists /> <RichTextEditor.Headings /> <RichTextEditor.Alignments /> </RichTextEditor.ControlsGroup> <RichTextEditor.ControlsGroup> <RichTextEditor.Link /> <RichTextEditor.Code /> </RichTextEditor.ControlsGroup> </RichTextEditor.Toolbar> </RichTextEditor> </FormProvider> ); }; ``` ```jsx render <Docs.AccessibilityTable title="Rich Text Editor" rows={[ { name: 'Control + Z', description: 'Undo', }, { name: 'Control + Shift + Z', description: 'Redo', }, { name: 'Control + B', description: 'Bold', }, { name: 'Control + I', description: 'Italic', }, { name: 'Control + U', description: 'Underline', }, { name: 'Control + E', description: 'Code', }, { name: 'Control + Shift + 7', description: 'Ordered list', }, { name: 'Control + Shift + 8', description: 'Bullet list', }, { name: 'Control + Shift + L', description: 'Left Align', }, { name: 'Control + Shift + E', description: 'Center Align', }, { name: 'Control + Shift + R', description: 'Right Align', }, { name: 'Control + Shift + J', description: 'Justify', }, { name: 'Control + Alt + 0', description: 'Normal Text', }, { name: 'Control + Alt + 1', description: 'Heading 1', }, { name: 'Control + Alt + 2', description: 'Heading 2', }, { name: 'Control + Alt + 3', description: 'Heading 3', }, { name: 'Control + Alt + 4', description: 'Heading 4', }, { name: 'Control + Alt + 5', description: 'Heading 5', }, { name: 'Control + Alt + 6', description: 'Heading 6', }, ]} /> ``` ```jsx render <Docs.AccessibilityTable title="Navigating Inside Toolbar" rows={[ { name: 'Right Arrow', description: 'Moves focus one cell to the right.', }, { name: 'Left Arrow', description: 'Moves focus one cell to the left.', }, { name: 'Enter', description: 'Select Item', }, ]} /> ``` </Tab> --- id: router category: Navigation title: Router description: Collection of navigational components that compose declaratively with your application. --- <Tab label="Overview"> ```jsx import { Router } from '@uhg-abyss/web/ui/Router'; ``` ## Usage Routes must be wrapped in an RouterProvider for navigation to work. Find additional resources on our RouterProvider component in [RouterProvider](/web/ui/router-provider). Routes are chosen based on the best match instead of being traversed in order. ```jsx live () => { const Page = ({ title }) => { return ( <div> <Router.MetaTags> <title>{title}</title> <meta name="description" content={title + 'Page'} /> </Router.MetaTags> <Heading css={{ 'abyss-heading-root': { marginTop: '15px' } }}> {title} Page </Heading> </div> ); }; return ( <RouterProvider history="memory" disableScroll> <ul> <li> <Link href="/">Home Page</Link> </li> <li> <Link href="/getting-started/">Getting Started</Link> </li> <li> <Link href="/web/ui/router">Router Routes</Link> </li> </ul> <Router.Routes> <Router.Route path="/" element={<Page title="Home" />} /> <Router.Route path="/getting-started/" element={<Page title="Getting Started" />} /> <Router.Route path="/web/ui/router/" element={<Page title="Router" />} /> </Router.Routes> </RouterProvider> ); }; ``` ## Link example `Link` is used to support components for Router. Use the `href` prop to set the link to a separate page. Find additional resources on our Link component in [Link](/web/ui/link). ```jsx live () => { const Page = ({ title }) => { return ( <div> <Router.MetaTags> <title>{title}</title> <meta name="description" /> </Router.MetaTags> </div> ); }; return ( <RouterProvider history="memory" disableScroll> <ul> <li> <Link href="/web/ui/router">Router Routes</Link> </li> </ul> <Router.Routes> <Router.Route path="/web/ui/router/" element={<Page title="Router" />} /> </Router.Routes> </RouterProvider> ); }; ``` ## Breadcrumbs example `Breadcrumbs` is used to integrate components with Router. Find additional resources on our Breadcrumbs component in [Breadcrumbs](/web/ui/breadcrumbs). ```jsx live () => { const Page = ({ title }) => { return ( <div> <Router.MetaTags> <title>{title}</title> <meta name="description" content={title + 'Page'} /> </Router.MetaTags> <Heading css={{ 'abyss-heading-root': { margin: '16px 0px' } }}> {title} Page </Heading> </div> ); }; return ( <RouterProvider history="memory" disableScroll> <React.Fragment> <Breadcrumbs divider="/" items={[ { title: 'Home', href: '/' }, { title: 'Getting Started', href: '/getting-started/' }, { title: 'Breadcrumbs', href: '/web/ui/breadcrumbs/' }, ]} /> <Router.Routes> <Router.Route path="/" element={<Page title="Home" />} /> <Router.Route path="/getting-started/" element={<Page title="Getting Started" />} /> <Router.Route path="/web/ui/breadcrumbs/" element={<Page title="Breadcrumbs" />} /> </Router.Routes> <Card> <Card.Title> Click on these links to mimic the use of breadcrumb navigation{' '} </Card.Title> <Card.Section> <ul style={{ display: 'inline-flex' }}> <li style={{ marginRight: '15px' }}> <Link href="/">Home Page</Link> </li> <li style={{ marginRight: '15px' }}> <Link href="/getting-started/">Getting Started</Link> </li> <li style={{ marginRight: '15px' }}> <Link href="/web/ui/breadcrumbs/">Breadcrumbs</Link> </li> </ul> </Card.Section> </Card> </React.Fragment> </RouterProvider> ); }; ``` ## Additional documentation Teams wanting to use React Router (v6) directly can import from these paths to ensure consistent versions across your application: ```tsx import { useLocation, useParams, } from '@uhg-abyss/web/tools/reactRouterTools/reactRouter'; ``` ```tsx import { Link, useNavigate, } from '@uhg-abyss/web/tools/reactRouterTools/reactRouterDom'; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={Router.Routes} rows={[ { name: 'title', type: 'string', description: 'The title of the router component', }, ]} /> ``` </Tab> --- id: router-provider category: Providers title: RouterProvider description: Used to render routes that match a location. --- <Tab label="Overview"> ```jsx import { RouterProvider } from '@uhg-abyss/web/ui/RouterProvider'; ``` ## Usage All Router objects are passed to this RouterProvider for navigation to work. RouterProvider leverages version 6.0+ of <ExitLink href='https://v5.reactrouter.com/web/guides/quick-start'>React Router Dom</ExitLink>. Find additional resources on our Router component in [Router](/web/ui/router). ```jsx render () => { const Page = ({ title }) => { return ( <div> <Router.MetaTags> <title>{title}</title> <meta name="description" content={title + 'Page'} /> </Router.MetaTags> <Heading css={{ 'abyss-heading-root': { marginTop: '15px' } }}> {title} Page </Heading> </div> ); }; return ( <RouterProvider history="memory" disableScroll> <Text fontWeight="bold" size="lg"> Example:{' '} </Text> <ul> <li> <Link href="/">Home Page</Link> </li> <li> <Link href="/getting-started/">Getting Started</Link> </li> <li> <Link href="/web/ui/router">Router Switch</Link> </li> </ul> <Router.Routes> <Router.Route path="/" element={<Page title="Home" />} /> <Router.Route path="/getting-started/" element={<Page title="Getting Started" />} /> <Router.Route path="/web/ui/router/" element={<Page title="Router" />} /> </Router.Routes> </RouterProvider> ); }; ``` ```jsx import { createRouter } from '@uhg-abyss/web/tools/createRouter'; const Page = ({ title }) => { return ( <div> <Router.MetaTags> <title>{title}</title> <meta name="description" content={title + 'Page'} /> </Router.MetaTags> <Heading css={{ 'abyss-heading-root': { marginTop: '15px' } }}> {title} Page </Heading> </div> ); }; const Routes = () => { return ( <Router.Routes> <Router.Route path="/" element={<Page title="Home" />} /> <Router.Route path="/getting-started/" element={<Page title="Getting Started" />} /> <Router.Route path="/web/ui/router/" element={<Page title="Router" />} /> </Router.Routes> ); }; const router = createRouter(Routes); export const browser = () => { return <RouterProvider router={router} />; }; ``` ## History Use the `history` prop to set the type of router provider. Types include `'browser'`, `'hash'`, and `'memory'`. The default is `browser`. - Browser: A router that uses the HTML5 history API (pushState, replaceState and the popstate event) to keep your UI in sync with the URL. - Hash: A router that uses the hash portion of the URL (i.e., window.location.hash) to keep your UI in sync with the URL. - IMPORTANT NOTE: Hash history does not support location.key or location.state. Any code or plugin that needs this behavior won’t work. As this technique is only intended to support legacy browsers, we encourage you to configure your server to work with type `'browser'` instead. - Memory: A router that keeps the history of your “URL” in memory (does not read or write to the address bar). ```jsx <RouterProvider history="hash"></RouterProvider> ``` ## Additional documentation Teams wanting to use React Router (v6) directly can import from these paths to ensure consistent versions across your application: ```tsx import { useLocation, useParams, } from '@uhg-abyss/web/tools/reactRouterTools/reactRouter'; ``` ```tsx import { Link, useNavigate, } from '@uhg-abyss/web/tools/reactRouterTools/reactRouterDom'; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={RouterProvider} rows={[ { name: 'children', type: 'ReactNode', description: 'The content of the router provider component', }, { name: 'history', type: 'string', description: 'Set the type of the route provider', }, { name: 'disableScroll', type: 'boolean', description: 'Disable auto-scrolling to top of page on location path change', }, ]} /> ``` </Tab> --- id: search-input-v2 category: Search title: V2SearchInput description: Provides an input field for searching content within a site to find specific items. design: https://www.figma.com/design/w88BfFK3ciGjZYLXuyVvfp/branch/fHSnFVjGiOoCGGao19yzdQ/Design-ready-Web%E2%80%A8Abyss-Global%E2%80%A8Component-Library?node-id=23504-938&m=dev subDirectory: SearchInput/v2 sourceIsTS: true isHidden: true --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="SearchInput"></Docs.V2MigrationBanner> ``` ```jsx import { V2SearchInput } from '@uhg-abyss/web/ui/SearchInput'; ``` ```jsx sandbox { component: 'V2SearchInput', inputs: [ { prop: 'placeholder', type: 'string', }, { prop: 'width', type: 'string', }, { prop: 'label', type: 'string', }, { prop: 'hideLabel', type: 'boolean', }, { prop: 'isClearable', type: 'boolean', }, { prop: 'isDisabled', type: 'boolean', }, { prop: 'isTypeAhead', type: 'boolean', }, ], } () => { const MockData = utils.useSearchInputMock(); const handleSearch = (data) => { console.log('Searched', data); }; return ( <V2SearchInput placeholder="Placeholder text" label="Search Sandbox" onSearch={handleSearch} options={MockData} /> ); }; ``` ## Usage `V2SearchInput` is designed specifically for site-wide search functionality, and is no longer considered a typical form input component. The recommended usage context is for a search input field that is used to search for items within a site and display results. For usages that require users to fill out a form with search functionality it is recommended you use [V2SelectInput](/web/ui/select-input-single-v2#search-filtering) with the `isSearchable` prop. Note: - `V2SearchInput` does not support the following V1 SearchInput props: `validators`, `errorMessage`, `isRequired`, `model` and `subText`. - `V2SearchInput` is no longer compatible with `FormProvider` and `useForm`. ## Variants ### Default search The default variant for `V2SearchInput` is a basic search input field that, on search, provides the search term to the [onSearch](#onsearch) callback. Note: All code examples below are using the type-ahead variant because of its increased functionality. Any props that are NOT compatible with the default variant are designated below by the following badge: ```jsx render <div style={{ marginTop: '-16px' }}> <V2Badge icon="remove_circle" variant="error"> Not compatible with Default </V2Badge> <Layout.Space space={24} /> </div> ``` ```jsx live-in-view () => { const handleSearch = (data) => { console.log('Searched', data); }; return ( <V2SearchInput label="SearchInput Default" isClearable onSearch={handleSearch} onFocus={(e) => { console.log('focus', e); }} onBlur={(e) => { console.log('onblur', e); }} onKeyDown={(e) => { console.log('onkeydown', e); }} onPaste={(e) => { console.log('onpaste', e); }} /> ); }; ``` ### Type ahead search Utilize the `isTypeAhead` prop to enable type-ahead search functionality along with a drop-down menu of options that are filtered based on the search term. Same as with the default variant, the [onSearch](#onsearch) callback is triggered on search. ```jsx live-in-view () => { const MockData = utils.useSearchInputMock(); return ( <V2SearchInput label="SearchInput Type Ahead" isClearable onSearch={(data) => console.log('searched', data)} options={MockData} onFocus={(e) => { console.log('focus', e); }} onBlur={(e) => { console.log('onblur', e); }} onKeyDown={(e) => { console.log('onkeydown', e); }} onPaste={(e) => { console.log('onpaste', e); }} isTypeAhead /> ); }; ``` ## State management ### Uncontrolled / onSearch When you only need to capture the searched value, simply use the [onSearch](#onsearch) prop. Note: Whether using controlled or uncontrolled, `onSearch` is always triggered on search. ```jsx live-in-view () => { const MockData = utils.useSearchInputMock(); const handleSearch = (data) => { console.log('Searched', data); }; return ( <V2SearchInput label="Uncontrolled" isClearable onSearch={handleSearch} options={MockData} isTypeAhead /> ); }; ``` ### Controlled / onInputChange When you need to store the current state of the input, use the `onInputChange` prop. This callback will be triggered on every input change, including on the type ahead variant when navigating with arrow keys or clicking an option from the drop-down menu. As a second argument, the callback will receive an `inputChangeType` parameter that designates the type of change that occurred. This can be useful when calling an API to fetch results based on the search term and you need to differentiate between types of user interaction. The `inputChangeType` parameter can have the following values. These values are available as constants via `import { V2SearchInputChangeTypes } from '@uhg-abyss/web/ui/SearchInput';`: | Type | Description | | ----------------- | --------------------------------------------- | | `InputChange` | User manually typed in the input field | | `InputClear` | User cleared the input using the clear button | | `ArrowNavigation` | User navigated with arrow keys | | `ItemClick` | User clicked on an item in the dropdown | <br /> Note: `V2SearchInput` no longer captures a drop-down menu selection separately from changes to the search input field. Therefore, to simplify operations, the `onChange` prop has been removed in favor of solely utilizing `onInputChange`. ```jsx live-in-view () => { const MockData = utils.useSearchInputMock(); const [inputValue, setInputValue] = useState(''); const handleInputChange = (value, inputChangeType) => { console.log({ value, inputChangeType }); // You can conditionally handle different input change types if (inputChangeType === V2SearchInputChangeTypes.ArrowNavigation) { // Handle arrow navigation differently if needed console.log('Arrow navigation', inputChangeType); } setInputValue(value); }; const handleSearch = (data) => { console.log('Searched', data); }; return ( <V2SearchInput label="Controlled Input State" isClearable onSearch={handleSearch} onInputChange={handleInputChange} value={inputValue} options={MockData} isTypeAhead /> ); }; ``` ## Display properties ### Label The `label` prop is required. The `hideLabel` prop can be set to `true` to hide the label visually, but still allow it to be accessible to screen readers. ```jsx live-in-view () => { const Spacing = styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }); const MockData = utils.useSearchInputMock(); return ( <Spacing> <V2SearchInput isTypeAhead isClearable onSearch={(data) => console.log('searched', data)} options={MockData} label="Active Label" /> <V2SearchInput isTypeAhead isClearable onSearch={(data) => console.log('searched', data)} options={MockData} label="Hidden Label" hideLabel /> </Spacing> ); }; ``` ### Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip-v2) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip-v2) or a [Popover](/web/ui/popover-v2). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip-v2/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live-in-view () => { const Spacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const MockData = utils.useSearchInputMock(); return ( <Spacing> <V2SearchInput isTypeAhead isClearable onSearch={(data) => console.log('searched', data)} label="Default Helper" helper="This is a tooltip" options={MockData} /> <V2SearchInput isTypeAhead isClearable onSearch={(data) => console.log('searched', data)} label="Custom Helper" helper={ <V2Popover title="Custom Helper" content="This is a popover with a custom icon" > <IconSymbol icon="help" variant="outlined" color="$success1" size="$md" /> </V2Popover> } options={MockData} /> </Spacing> ); }; ``` ### Placeholder Use the `placeholder` prop to set the placeholder text. ```jsx live-in-view () => { const MockData = utils.useSearchInputMock(); return ( <V2SearchInput label="Placeholder" isTypeAhead isClearable onSearch={(data) => console.log('searched', data)} options={MockData} placeholder="Placeholder text" /> ); }; ``` ### Width Use the `width` prop to set the width of the select list. ```jsx live-in-view () => { const Spacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const MockData = utils.useSearchInputMock(); return ( <Spacing> <V2SearchInput label="Default Width" isTypeAhead isClearable onSearch={(data) => console.log('searched', data)} options={MockData} /> <V2SearchInput label="Width 75%" isTypeAhead isClearable onSearch={(data) => console.log('searched', data)} options={MockData} width="75%" /> <V2SearchInput label="Width 300px" isTypeAhead isClearable onSearch={(data) => console.log('searched', data)} options={MockData} width="300px" /> </Spacing> ); }; ``` ## Interactivity ### onSearch Use the `onSearch` prop to capture the searched value. The callback will receive the selected search term string as the first argument, and if applicable when using type-ahead, as a second argument, the entire object of the selected option. A search occurs with the following actions: - Pressing "Enter" when focused on the input field. - Selecting on an option from the drop-down menu. - Clicking or pressing "Enter" on the default variant's search button. ```jsx live-in-view () => { const MockData = utils.useSearchInputMock(); const handleSearch = (searchedValue, searchedOption) => { console.log('Searched:', searchedValue, searchedOption); }; return ( <V2SearchInput placeholder="Placeholder text" label="SearchInput Type Ahead" isClearable onSearch={handleSearch} options={MockData} isTypeAhead /> ); }; ``` ### Clearable Use the `isClearable` prop to allow for clearing the search input. If `true`, a clear button will appear in the input. The optional `onClear` callback prop can be used to trigger additional actions when the clear button is clicked. ```jsx live-in-view () => { const MockData = utils.useSearchInputMock(); return ( <V2SearchInput label="Clearable" isTypeAhead onSearch={(data) => console.log('searched', data)} onClear={() => console.log('selection cleared')} options={MockData} isClearable /> ); }; ``` ### Disabled Set the `isDisabled` prop to `true` to disable the search input field. ```jsx live-in-view () => { const MockData = utils.useSearchInputMock(); return ( <V2SearchInput label="Disabled" isTypeAhead isClearable onSearch={(data) => console.log('searched', data)} options={MockData} isDisabled /> ); }; ``` ### onFocusOpen ```jsx render <> <V2Badge icon="remove_circle" variant="error"> Not compatible with Default </V2Badge> <Layout.Space /> </> ``` To automatically open the menu when the input receives keyboard focus, use the `onFocusOpen` prop. Note: By default, the menu will automatically open when clicked. ```jsx live-in-view () => { const MockData = utils.useSearchInputMock(); return ( <V2SearchInput label="Open On Focus" isTypeAhead isClearable onSearch={(data) => console.log('searched', data)} options={MockData} onFocusOpen /> ); }; ``` ### Enable outside scroll ```jsx render <> <V2Badge icon="remove_circle" variant="error"> Not compatible with Default </V2Badge> <Layout.Space /> </> ``` Set the `enableOutsideScroll` prop to `true` to enable scrolling outside the search input component while the option list is open. Default is set to `false`. ```jsx live-in-view () => { const MockData = utils.useSearchInputMock(); return ( <V2SearchInput label="Enable Outside Scroll" isTypeAhead isClearable onSearch={(data) => console.log('searched', data)} options={MockData} enableOutsideScroll /> ); }; ``` ## Search filtering ```jsx render <V2Badge icon="remove_circle" variant="error"> Not compatible with Default </V2Badge> ``` ### Fuse.js SearchInput uses the <ExitLink href="https://fusejs.io">Fuse.js</ExitLink> library to fuzzy filter results. What is fuzzy searching?... Generally speaking, fuzzy searching (more formally known as approximate string matching) is the technique of finding strings that are approximately equal to a given pattern (rather than exactly). ```jsx live () => { const MockData = utils.useSearchInputMock(); return ( <V2SearchInput label="Fuse Default Search" isTypeAhead isClearable onSearch={(data) => console.log('searched', data)} options={MockData} /> ); }; ``` ### Fuse keys The `keys` prop allows you to specify the values from the specific keys within your `options` object to search against. This feature accommodates nested paths, prioritizes certain fields with weighted search, and can handle searches within arrays of objects. The default search keys are `['label', 'value']`. For example, if the `options` contained objects of the following structure: ```ts { value: "react", label: "React", tags: ['jsx', 'virtual dom', 'facebook'] } ``` and you wanted to allow users to search on the label and tags values, you would provide the following, as in the example below: ```tsx searchConfig={{ keys: ['label', 'tags'] }} ``` ```jsx live-in-view () => { const MockData = utils.useSearchInputMock(); return ( <V2SearchInput label="Fuse Keys Search" isTypeAhead isClearable onSearch={(data) => console.log('searched', data)} options={[ { value: 'react', label: 'React', tags: ['jsx', 'virtual dom', 'facebook'], }, { value: 'ng', label: 'Angular', tags: ['typescript', 'directives', 'google'], }, { value: 'svelte', label: 'Svelte', tags: ['compile-time', 'no virtual dom', 'rich harris'], }, ]} searchConfig={{ keys: ['label', 'tags'] }} /> ); }; ``` ### Custom Fuse configurations The Fuse configuration can be customized by following the <ExitLink href="https://fusejs.io/api/options.html">Fuse documentation</ExitLink> and passing the configurations into the `searchConfig` prop. For example, if you wanted to adjust the <ExitLink href="https://www.fusejs.io/api/options.html#threshold">threshold</ExitLink> to `0`, thus requiring an exact match, you would pass in the following object. The default threshold is `0.1`. Common config props: - `keys`: Array of keys to search against - `threshold`: Threshold for fuzzy search - `maxResults`: Maximum number of results to return - `debounce`: Debounce time in milliseconds ```tsx const customFuseConfig = { threshold: 0, // exact match }; ``` ```jsx live-in-view () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const [sliderValue, setSliderValue] = useState(0); const customSearchConfig = { threshold: sliderValue / 100, keys: ['label'], }; return ( <FormSpacing> <V2SearchInput label="Custom Fuse Threshold Config" isTypeAhead isClearable onSearch={(data) => console.log('searched', data)} options={[ { value: 'react', label: 'React', tags: ['jsx', 'virtual dom', 'facebook'], }, { value: 'ng', label: 'Angular', tags: ['typescript', 'directives', 'google'], }, { value: 'svelte', label: 'Svelte', tags: ['compile-time', 'no virtual dom', 'rich harris'], }, ]} searchConfig={customSearchConfig} /> <Slider css={{ 'abyss-slider-label': { marginTop: '20px', }, '&.abyss-slider-root': { width: '85%', marginLeft: 'auto', marginRight: 'auto', }, }} label="Search Threshold" value={sliderValue} onChange={setSliderValue} step={20} showMarks marks={[ { value: 0, label: 'Exact Match' }, { value: 20, label: '.2' }, { value: 40, label: '.4' }, { value: 60, label: '.6' }, { value: 80, label: '.8' }, { value: 100, label: 'Match Anything' }, ]} /> </FormSpacing> ); }; ``` ### Highlighted search results By default, when searching, the matching text within all search results will be highlighted, and the font weight will be updated based on the following criteria: - not selected: the matching text displays as bold - selected: the matching text displays as regular To override this behavior and turn off the highlighting, set the `highlightMatches` prop to `false`. ```jsx live-in-view () => { const [highlightMatches, setHighlightMatches] = useState(true); return ( <React.Fragment> <V2SearchInput label="Highlighted Search Results" isTypeAhead isClearable onSearch={(data) => console.log('searched', data)} options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'preact', label: 'Preact' }, ]} highlightMatches={highlightMatches} /> <V2Button onClick={() => setHighlightMatches(!highlightMatches)} css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > {highlightMatches ? 'Disable' : 'Enable'} Search Highlighting </V2Button> </React.Fragment> ); }; ``` ### API filtering with debounce To override the Fuse filtering and make asynchronous calls to an API to set the list of dropdown options, use a combination of the `onInputChange` and `options` props. While searching, `onInputChange` will supply the current search value and whether the input field was updated due to a selection. After retrieving the option items from the API, pass them into the `options` prop. To incorporate debouncing into the search, use the `useDebounce` hook. ```jsx import { useDebounce } from '@uhg-abyss/web/hooks/useDebounce'; ``` This example shows all of these concepts together. The apiFilter function is called on every keystroke, but the API call is debounced to only occur after 300ms of inactivity. Search "united" to see the API call in action. ```jsx live-in-view () => { const [results, setResults] = useState([]); const apiFilter = (searchValue, inputChangeType) => { console.log('searchValue', searchValue); console.log('inputChangeType', inputChangeType); // If input field updated due to arrow navigation, do not make an API call if (inputChangeType === V2SearchInputChangeTypes.ArrowNavigation) { return; } if (!searchValue) { setResults([]); return; } utils.useSearchInputMockApi(searchValue).then((response) => { console.log({ results, response }); setResults(response); }); }; const debouncedApiFilter = useDebounce(apiFilter, 300); // function, delay (ms) return ( <V2SearchInput label="API Filtering" isTypeAhead isClearable onSearch={(data) => console.log('searched', data)} options={results} onInputChange={debouncedApiFilter} /> ); }; ``` ## Menu option configurations ```jsx render <V2Badge icon="remove_circle" variant="error"> Not compatible with Default </V2Badge> ``` ### Options Use the `options` prop to supply the drop-down menu options that will be available for selection. `options` is an array of objects, where each object has a base that includes the following properties: - `value`: unique identifier for the option - `label`: content the option will display within the menu list ```jsx [ { value: 'id1', label: 'Option 1' }, { value: 'id2', label: 'Option 2' }, { value: 'id3', label: 'Option 3' }, ... ] ``` Sections can also be specified. See [Section Headers](#section-headers) for more details. ### ValueKey / labelKey If your data structure uses different property names than `value` and `label`, you can map them using the `valueKey` and `labelKey` props without restructuring your data. - `valueKey`: Specifies which property to use as the option's value (defaults to `"value"`) - `labelKey`: Specifies which property to use as the option's display text (defaults to `"label"`) This is particularly useful when working with API responses or existing data structures that can't be easily transformed. ```jsx live-in-view () => { return ( <V2SearchInput label="Label/Value Keys" isTypeAhead isClearable onSearch={(selectedSearchTerm, selectedOption) => console.log('Searched:', selectedSearchTerm, selectedOption) } options={[ { name: 'Custom Option 1', id: 'a1' }, { name: 'Custom Option 2', id: 'b2' }, { name: 'Custom Option 3', id: 'c3' }, ]} labelKey="name" valueKey="id" /> ); }; ``` ### Disable option items Disable an individual option item by setting the `isDisabled` key to `true` within the object. ```jsx live-in-view () => { const MockData = [ { label: 'UnitedHealthcare Claim Estimator', value: 'UnitedHealthcare Claim Estimator', }, { label: 'UnitedHealthcare CommunityCare', value: 'UnitedHealthcare CommunityCare', isDisabled: true, }, { label: 'UnitedHealthcare Oxford', value: 'UnitedHealthcare Oxford', }, ]; return ( <V2SearchInput label="Disable Option Items" isTypeAhead isClearable onSearch={(data) => console.log('searched', data)} options={MockData} /> ); }; ``` ### Option list height Use the `maxListHeight` prop to set the maximum height the option list can be before it becomes scrollable. The default value is `185px`. ```jsx live-in-view () => { const Spacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const MockData = utils.useSearchInputMock(); return ( <Spacing> <V2SearchInput label="100px max height" isTypeAhead isClearable onSearch={(data) => console.log('searched', data)} options={MockData} maxListHeight={100} /> <V2SearchInput label="185px max height - Default" isTypeAhead isClearable onSearch={(data) => console.log('searched', data)} options={MockData} /> <V2SearchInput label="250px max height" isTypeAhead isClearable onSearch={(data) => console.log('searched', data)} options={MockData} maxListHeight="250px" /> </Spacing> ); }; ``` ### Section headers To group list items under section headers, pass objects into the `options` array that have the `section` and `items` properties. `section` specifies the name of the section, which will be bolded and unselectable, while `items` contains the options within that section (with the same `value`/`label` format as normal), which will appear indented. To retain section headers after searching with `isSearchable`, set `retainSectionHeader` within `searchConfig` to `true`. ```jsx [ { value: 'id1', label: 'Option 1' }, { value: 'id2', label: 'Option 2' }, { section: 'Section Header', items: [ { value: 'id3', label: 'Sub-section Option 1' }, { value: 'id4', label: 'Sub-section Option 2' }, ... ], }, ... ] ``` ```jsx live-in-view () => { const [value, setValue] = React.useState(''); return ( <V2SearchInput label="Section Headers Example" isTypeAhead isClearable onSearch={(data) => console.log('searched', data)} searchConfig={{ retainSectionHeader: true }} options={[ { value: '1', label: 'This option is not under any section' }, { section: 'Section Header', items: [ { value: '11', label: 'Option 1' }, { value: '21', label: 'Option 2' }, ], }, { section: 'Other Section Header', items: [ { value: '31', label: 'Option 3' }, { value: '41', label: 'Option 4' }, ], }, ]} /> ); }; ``` ### Custom render Use the `customRender` prop to customize the render of each option item. If [section headers](#section-headers) are used, they will also be handled by this function. `customRender` provides the item object as the first parameter and the item's state as the second. ```jsx live-in-view () => { const customRender = (item, state) => { console.log('item', item); const defaultSettings = { icon: 'cancel', color: '$error1', variant: 'error', }; const getSettings = () => { const { status } = item; if (status === 'active') { return { icon: 'check_circle_outline', color: '$success1', variant: 'success', }; } return defaultSettings; }; const { icon, color, variant } = getSettings(); if (item.section) { return ( <Layout.Group> <span>{item.section}</span> <IconSymbol icon={icon} color={color} /> </Layout.Group> ); } return <Badge variant={variant}>{item.label}</Badge>; }; return ( <V2SearchInput label="Custom Render" isTypeAhead isClearable onSearch={(data) => console.log('searched', data)} maxListHeight={300} options={[ { section: 'Active Options', status: 'active', items: [ { value: 'option_1', label: 'Option 1', status: 'active' }, { value: 'option_2', label: 'Option 2', status: 'active' }, { value: 'option_3', label: 'Option 3', status: 'active' }, ], }, { section: 'Inactive Options', status: 'inactive', items: [ { value: 'option_4', label: 'Option 4', status: 'inactive' }, { value: 'option_5', label: 'Option 5', status: 'inactive' }, { value: 'option_6', label: 'Option 6', status: 'inactive' }, ], }, ]} customRender={customRender} /> ); }; ``` ### Virtualization Use the `virtual` prop to add virtualization and improve performance when working with larger data sets. Virtualization leverages the `useVirtualization` hook, which utilizes the TanStack Virtual library. Setting `virtual` to `true` will utilize the default configuration. `virtual` also accepts an object to configure the virtualizer. To see all available values that may be provided to the `virtual` prop, please refer to the [TanStack Virtual documentation](https://tanstack.com/virtual/v3/docs/api/virtualizer). To maximize performance, virtualization for the V2SearchInput component is configured by default to use fixed sizing based on an option item element height of `38px`. If your item height remains fixed but is different from the default, utilize the [estimateSize](https://tanstack.com/virtual/latest/docs/api/virtualizer#estimatesize) function. If the item height is unknown prior to rendering, enable dynamic sizing by setting `dynamicSizing` to `true`. The default settings used in V2SearchInput are as follows: - `estimateSize`: Sets item height when using fixed sizing. When using dynamic sizing, to help with scroll performance, set this to the largest possible height of the item elements (default value is `38`). - `dynamicSizing`: When `true`, each option item element is dynamically measured on render. Scrolling performance may not be as smooth when using this prop (default value is `false`). - `overscan`: The number of element items to render above and below the visible area (default value is `5`). ```jsx live-in-view () => { const Spacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const defaultOptionCount = 5000; const withSectionHeaders = false; const optionNumberForm = useFormV2({ defaultValues: { optionCount: defaultOptionCount, }, }); const [options, setOptions] = React.useState(); const generateOptions = (count) => { const options = Array.from(Array(Number(count)).keys()).map((i) => { const optionLabelValue = `Option ${i + 1}`; if (withSectionHeaders) { return { section: `Option ${i + 1} Header`, items: [ { label: `${optionLabelValue} A`, value: `${optionLabelValue}_A` }, { label: `${optionLabelValue} B`, value: `${optionLabelValue}_B` }, ], }; } return { label: optionLabelValue, value: optionLabelValue }; }); setOptions(options); }; useEffect(() => { generateOptions(defaultOptionCount); }, []); return ( <React.Fragment> <Spacing> <V2FormProvider state={optionNumberForm} onSubmit={({ optionCount }) => generateOptions(optionCount)} > <Layout.Group alignItems="bottom"> <V2TextInput label="Set Number of Dropdown Options" model="optionCount" mask="numeric" maskConfig={{ isAllowed: ({ floatValue }) => { const value = floatValue || 0; return value <= 100000; }, }} /> <V2Button type="submit">Update Options</V2Button> <V2Button variant="outline" type="button" onClick={() => { optionNumberForm.reset(); generateOptions(defaultOptionCount); }} > Reset </V2Button> </Layout.Group> </V2FormProvider> <V2SearchInput label="SearchInput with Virtualization" isTypeAhead isClearable onSearch={(data, selection) => console.log('searched', data, selection) } options={options} searchConfig={{ retainSectionHeader: withSectionHeaders }} virtual /> <V2SearchInput label="SearchInput without Virtualization" isTypeAhead isClearable onSearch={(data, selection) => console.log('searched', data, selection) } options={options} searchConfig={{ retainSectionHeader: withSectionHeaders }} /> </Spacing> </React.Fragment> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2SearchInput (Default)" propTypeName="SearchInputDefaultProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="V2SearchInput (Typeahead)" propTypeName="SearchInputTypeAheadProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2ClassesTable title="V2SearchInput" classes={[SearchInputClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> A combobox is a widget made up of the combination of two distinct elements: 1) a single-line textbox, and 2) an associated pop-up element for helping users set the value of the textbox. The popup may be a listbox, grid, tree, or dialog. Many implementations also include a third optional element -- a graphical button adjacent to the textbox, indicating the availability of the popup. Activating the button displays the popup if suggestions are available. Adheres to the <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/combobox/">Combo box WAI-ARIA design pattern.</ExitLink>. Example: <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-both/">Editable Combobox With Both List and Inline Autocomplete</ExitLink> <h2>Include meaningful accessible labels, even when not displayed</h2> All V2SearchInput fields must include a meaningful label, even if hidden (using `hideLabel`). This should start with the word "Search", especially if there is any visible text that suggests that (such as `placeholder="Search..."`). If this is not possible or part of the design, use the `I18nProvider` to prepend `"Search "` to the `aria-label` (as shown in second example below). ```jsx live () => { return ( <V2SearchInput label="Meal options" placeholder="Search our menu..." isClearable isTypeAhead helper="Showing reduced menu" onSearch={(data) => console.log('searched', data)} searchConfig={{ threshold: 0.1, retainSectionHeader: true }} options={[ { value: '1', label: 'Water' }, { section: 'Drinks', items: [ { value: '10', label: 'Soft drinks' }, { value: '20', label: 'Milk' }, ], }, { section: 'Entrees', items: [ { value: '11', label: 'Hamburger' }, { value: '21', label: 'Chicken Tenders' }, ], }, { section: 'Sides', items: [ { value: '31', label: 'French Fries' }, { value: '41', label: 'Onion Rings' }, ], }, ]} /> ); }; ``` ```jsx live () => { const MockData = utils.useSearchInputMock(); return ( <I18nProvider translations={{ V2SearchInput: { aria: { searchButton: { label: 'Search for plan documents', }, }, }, }} > <V2SearchInput isClearable onSearch={(data) => console.log('searched', data)} label="Plan documents" placeholder="PDFs only" helper={ <V2Popover title="Default operation" content="This example does not use type ahead. As a result it includes a search button." > <IconSymbol icon="brightness_alert" variant="outlined" color="$success1" title="Document search help" size="$md" /> </V2Popover> } options={MockData} /> </I18nProvider> ); }; ``` <h2>Typeahead Variant Keyboard Interactions</h2> ```jsx render <Docs.AccessibilityTable title="Textbox" rows={[ { name: 'Down Arrow', description: 'If the listbox is displayed: Moves focus to the second suggested value. Note that the first value is automatically selected. If the listbox is not displayed: opens the listbox and moves focus to the first value', }, { name: 'Up Arrow', description: 'If the listbox is displayed, moves focus to the last suggested value. If the listbox is not displayed, opens the listbox and moves focus to the last value', }, { name: 'Alt + Down Arrow', description: 'Opens the listbox without moving focus or changing selection', }, { name: 'Enter', description: 'If the listbox is displayed and the first option is automatically selected: Sets the textbox value to the content of the selected option. Closes the listbox', }, { name: 'Esc', description: 'Clears the textbox. If the listbox is displayed, closes it', }, ]} /> ``` ```jsx render <Docs.AccessibilityTable title="Listbox" rows={[ { name: 'Enter', description: 'Sets the textbox value to the content of the focused option in the listbox. Closes the listbox. Sets focus on the textbox', }, { name: 'Esc', description: 'Closes the listbox. Sets focus on the textbox. Clears the textbox', }, { name: 'Down Arrow', description: 'Moves focus to the next option. If focus is on the last option, moves focus to the first option', }, { name: 'Up Arrow', description: 'Moves focus to the previous option. If focus is on the first option, moves focus to the last option', }, { name: 'Right Arrow', description: 'Moves focus to the textbox and moves the editing cursor one character to the right', }, { name: 'Left Arrow', description: 'Moves focus to the textbox and moves the editing cursor one character to the left', }, { name: 'Home', description: 'Moves focus to the textbox and places the editing cursor at the beginning of the field', }, { name: 'End', description: 'Moves focus to the textbox and places the editing cursor at the end of the field', }, ]} /> ``` </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={SearchInput} keys={['searchInputV2']} /> ``` </Tab> --- id: search-input category: Forms title: SearchInput description: Provides an input field for searching content within a site to find specific items. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=4082-25244 --- <Tab label="Overview"> ```jsx import { SearchInput } from '@uhg-abyss/web/ui/SearchInput'; ``` ```jsx sandbox { component: 'SearchInput', inputs: [ { prop: 'placeholder', type: 'string', }, { prop: 'height', type: 'string', }, { prop: 'width', type: 'string', }, { prop: 'uniqueStorageId', type: 'string', }, { prop: 'label', type: 'string', }, { prop: 'resultLimit', type: 'number', }, { prop: 'hideLabel', type: 'boolean', }, { prop: 'rounded', type: 'boolean', }, { prop: 'isClearable', type: 'boolean', }, { prop: 'isDisabled', type: 'boolean', }, ], } () => { const MockData = utils.useSearchInputMock(); const [value, setValue] = React.useState(''); const handleSearch = (data) => { console.log('Searched', data); }; return ( <SearchInput placeholder="Search Sandbox..." uniqueStorageId="search-input-sandbox" label="Search Sandbox" hideLabel value={value} onChange={setValue} onSearch={handleSearch} onClear={() => setValue('')} options={MockData} keys={['value']} /> ); }; ``` ## useForm (recommended) Using the `useForm` hook lets the DOM handle form data. ```jsx live () => { const MockData = utils.useSearchInputMock(); const form = useForm(); const handleSearch = (data) => { console.log('Searched', data); }; return ( <FormProvider state={form}> <SearchInput placeholder="Search useForm..." model="search-input-form" label="useForm" hideLabel onClickSearchButton={() => {}} options={MockData} onSearch={handleSearch} keys={['value']} /> </FormProvider> ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const MockData = utils.useSearchInputMock(); const [value, setValue] = React.useState(''); const handleSearch = (data) => { console.log('Searched', data); }; const onChange = (newValue, selectedOption) => { console.log('onChange newValue:', newValue); console.log('onChange selectedOption', selectedOption); setValue(newValue); }; return ( <SearchInput placeholder="Search useState..." uniqueStorageId="search-input-state" value={value} label="useState" hideLabel onChange={onChange} onSearch={handleSearch} onClear={() => setValue('')} isClearable options={MockData} keys={['value']} /> ); }; ``` ## Section headers To create section headers in the list, pass objects into the `options` array that have the `section` and `items` properties. `section` specifies the name of the section, which will be bolded and unselectable, while `items` should contain the options within that section (with the same `value`/`label` format as normal), which will appear indented. The `retainSectionHeader` prop can be passed in to retain the corresponding section headers in the results when searching. ```jsx live () => { const [value, setValue] = React.useState(''); return ( <SearchInput label="Section Headers Example" hideLabel placeholder="Search..." value={value} onChange={setValue} onClear={() => setValue('')} openOnFocus resultLimit={6} fuseConfig={{ threshold: 0.1 }} retainSectionHeader options={[ { value: '1', label: 'This option is not under any section' }, { section: 'Section Header', items: [ { value: '11', label: 'Option 1' }, { value: '21', label: 'Option 2' }, ], }, { section: 'Other Section Header', items: [ { value: '31', label: 'Option 3' }, { value: '41', label: 'Option 4' }, ], }, ]} /> ); }; ``` ## Fuse.js SearchInput uses the <ExitLink href="https://fusejs.io">Fuse.js</ExitLink> library to fuzzy filter results. What is fuzzy searching?... Generally speaking, fuzzy searching (more formally known as approximate string matching) is the technique of finding strings that are approximately equal to a given pattern (rather than exactly). ```jsx live () => { const MockData = utils.useSearchInputMock(); const form = useForm(); return ( <FormProvider state={form}> <SearchInput placeholder="Search..." model="search" label="Fuse Default Search" isClearable isSearchable options={MockData} /> </FormProvider> ); }; ``` ### Fuse keys The `keys` prop allows you to specify the values from the specific keys within your `options` object to search against. This feature accommodates nested paths, prioritizes certain fields with weighted search, and can handle searches within arrays of objects. The default search keys are `['label', 'value']`. For example, if you wanted to search on the `label` and `tags` values in your object, you would pass in `keys={['label', 'tags']}`. ```javascript { id: 'UnitedHealthcare Claims Research Project', label: 'UnitedHealthcare Claims Research Project', link: '/claims/research', tags: ['internal'], value: 'UnitedHealthcare Claims Research Project', } ``` ```jsx live () => { const MockData = utils.useSearchInputMock(); console.log('MockData', MockData); const form = useForm(); const handleSearch = (data) => { console.log('Searched!', data); }; return ( <FormProvider state={form}> <SearchInput keys={['label', 'tags']} placeholder="Search..." model="search" label="Fuse Keys Search" options={MockData} onSearch={handleSearch} /> </FormProvider> ); }; ``` ### Custom Fuse configurations You can customize the fuse filter by following the documentation on <ExitLink href="https://fusejs.io/api/options.html">Fuse</ExitLink> and passing your configurations into the `fuseConfig` prop. For example, if you wanted to adjust the <ExitLink href="https://www.fusejs.io/api/options.html#threshold">threshold</ExitLink> to `0` so the search criteria requires an exact match, you would pass in the following object. The default threshold is `0.4`. ```jsx const customFuseConfig = { threshold: 0, // exact match }; ``` ```jsx live () => { const [sliderValue, setSliderValue] = useState(0); const MockData = utils.useSearchInputMock(); const form = useForm(); const customFuseConfig = { threshold: sliderValue / 100, }; const handleSearch = (data) => { console.log('Searched!', data); }; return ( <FormProvider state={form}> <SearchInput placeholder="Search..." keys={['label']} fuseConfig={customFuseConfig} model="search" label="Custom Fuse Configuration" options={MockData} onSearch={handleSearch} /> <Slider css={{ 'abyss-slider-label': { marginTop: '20px', }, '&.abyss-slider-root': { width: '85%', marginLeft: 'auto', marginRight: 'auto', }, }} label="Search Threshold" value={sliderValue} onChange={setSliderValue} step={20} showMarks marks={[ { value: 0, label: 'Exact Match' }, { value: 20, label: '.2' }, { value: 40, label: '.4' }, { value: 60, label: '.6' }, { value: 80, label: '.8' }, { value: 100, label: 'Match Anything' }, ]} /> </FormProvider> ); }; ``` ## Loading Use the `isLoading` prop to display the default skeleton loader on search. If you'd like to use a custom loader, pass a node into the `customLoader` prop. ```jsx live () => { const MockData = utils.useSearchInputMock(); const form = useForm({ defaultValues: { loaderType: 'default', showLoader: false, }, }); const { loaderType, showLoader } = form.watch(); const customLoader = ( <LoadingSpinner size="$sm" isLoading ariaLoadingLabel="Loading page" /> ); const onInputChange = (value, isArrowKeyDown) => { if (isArrowKeyDown) return; if (value) { form.setValue('showLoader', true); setTimeout(() => { form.setValue('showLoader', false); }, 2000); } }; return ( <FormProvider state={form}> <SearchInput label="Loading" hideLabel placeholder="Search to see loader..." model="search" options={MockData} isLoading={showLoader} onInputChange={onInputChange} {...(loaderType === 'custom' && { customLoader })} /> <RadioGroup display="row" label="Select Loader" model="loaderType"> <RadioGroup.Radio label="Default Loader" value="default" /> <RadioGroup.Radio label="Custom Loader" value="custom" /> </RadioGroup> </FormProvider> ); }; ``` ## Custom filtering Use the `customFilter` prop to override the fuse.js filtering. The results returned from your customFilter function should be passed into the `options` prop. ```jsx live () => { const MockData = utils.useSearchInputMock(); const [results, setResults] = React.useState([]); const form = useForm(); const handleSearch = (data) => { console.log('Searched', data); }; const customFilter = (currentValue) => { if (currentValue) { const updatedList = MockData.filter((item) => { return item.value.toUpperCase().includes(currentValue.toUpperCase()); }); setResults(updatedList); return updatedList; } }; return ( <FormProvider state={form}> <SearchInput placeholder="Search..." model="search" label="Custom Filtering" hideLabel customFilter={customFilter} onSearch={handleSearch} options={results} /> </FormProvider> ); }; ``` ## API filtering with debounce Use the `apiFiltering` prop to override the fuse.js filtering and supply a custom function to make asynchronous calls to an API. Both current value and selected value results will be passed to the apiFiltering callback. The results from your API should be passed into the `options` prop. If `debounceTime` is not passed, a default debounce time of 1000ms will be applied. In the example below, search by the string `united` to see results. ```jsx live () => { const [results, setResults] = useState([]); const [loading, setLoading] = useState(false); const form = useForm(); const handleSearch = (data) => { console.log('Searched', data); }; const apiFilter = (currentValue, selectedValue) => { console.log('currentValue', currentValue); console.log('selectedValue', selectedValue); setLoading(true); utils.useSearchInputMockApi(currentValue).then((response) => { setLoading(false); setResults(response); }); }; return ( <FormProvider state={form}> <SearchInput placeholder="Search..." model="search" label="Api Filtering" onInputChange={(inputValue, isArrowKeyDown) => { if (!isArrowKeyDown) { setLoading(true); } }} hideLabel apiFiltering={apiFilter} onSearch={handleSearch} options={results} isLoading={loading} debounceTime={1200} /> </FormProvider> ); }; ``` ## Result limit Use the `resultLimit` to choose how many results are shown at a time. The default limit is set to `6`. ```jsx live () => { const MockData = utils.useSearchInputMock(); const form = useForm(); const handleSearch = (data) => { console.log('Searched', data); }; return ( <FormProvider state={form}> <SearchInput resultLimit={3} placeholder="Search..." model="search" label="Result Limit" hideLabel options={MockData} onSearch={handleSearch} keys={['value']} /> </FormProvider> ); }; ``` ## Local storage To automatically store the users recent searches pass the `uniqueStorageId` prop to have the config stored locally. ```jsx live () => { const MockData = utils.useSearchInputMock(); const form = useForm(); const handleSearch = (data) => { console.log('Searched', data); }; return ( <FormProvider state={form}> <SearchInput placeholder="Search..." model="search" label="Local Storage" hideLabel options={MockData} onSearch={handleSearch} keys={['value']} uniqueStorageId="search-input-storage-id" /> </FormProvider> ); }; ``` ## Clearable Set the `isClearable` prop to `true` to display a clear button in the input field. Use the `onClear` prop to handle the clear action for controlled inputs. ```jsx live () => { const MockData = utils.useSearchInputMock(); const form = useForm(); const handleSearch = (data) => { console.log('Searched', data); }; return ( <FormProvider state={form}> <SearchInput resultLimit={3} label="Clearable" hideLabel placeholder="Search..." model="search" options={MockData} isClearable onSearch={handleSearch} keys={['value']} /> </FormProvider> ); }; ``` ## Custom result render Use the `customRender` prop to customize the render of each option item. ```jsx live () => { const MockData = utils.useSearchInputMock(); const form = useForm(); const handleSearch = (data) => { console.log('Searched', data); }; return ( <FormProvider state={form}> <SearchInput resultLimit={3} label="Custom Render" hideLabel placeholder="Search..." model="search" options={MockData} onSearch={handleSearch} keys={['value']} customRender={(item) => { return ( <div> <b>Custom Render: </b> {item.value} </div> ); }} /> </FormProvider> ); }; ``` ## Custom 'no options' message Use the `customNoOptionsMessage` prop to customize the message displayed when there are no options returned by the search. If `customNoOptionsMessage` prop is null, the default message is 'No Options'. ```jsx live () => { const form = useForm(); const handleSearch = (data) => { console.log('Searched', data); }; return ( <FormProvider state={form}> <SearchInput resultLimit={3} label="Custom No Options Message" hideLabel placeholder="Search..." model="search" onSearch={handleSearch} keys={['value']} customNoOptionsMessage="This is a custom message displayed when there are no options to choose" /> </FormProvider> ); }; ``` ## Change or remove icon Use the `inputIcon` prop to change or remove the default search icon in the input field. Use the `optionIcon` prop to change or remove the default search icons in the dropdown menu. The example below changes the default search icons. Search by the string `united` to see the changed dropdown menu icons. ```jsx live () => { const MockData = utils.useSearchInputMock(); const form = useForm(); const handleSearch = (data) => { console.log('Searched', data); }; return ( <FormProvider state={form}> <SearchInput placeholder="Search..." model="search-input-form" label="useForm" hideLabel isClearable options={MockData} onSearch={handleSearch} keys={['value']} optionIcon={<IconSymbol icon="star" />} inputIcon={<IconSymbol icon="star" />} /> </FormProvider> ); }; ``` The example below removes the default search icons. Search by the string `united` to see the removed dropdown menu icons. ```jsx live () => { const MockData = utils.useSearchInputMock(); const form = useForm(); const handleSearch = (data) => { console.log('Searched', data); }; return ( <FormProvider state={form}> <SearchInput placeholder="Search..." model="search-input-form" label="useForm" hideLabel isClearable options={MockData} onSearch={handleSearch} keys={['value']} optionIcon={null} inputIcon={null} /> </FormProvider> ); }; ``` ## Add elements inside input Use the `inputLeftElement` and `inputRightElement` props to add elements to the inside of the search input field. The recommended usage is for inserting icons. These are considered decorative and do not need to be exposed to screen readers. That said, please note that icons should _not_ provide any information that is not also conveyed in a screen-readable way. For example, an (!) icon to indicate errors needs to be accompanied by `aria-invalid`. If icons are used to convey additional information, use the `inputLeftElementDescription` and `inputRightElementDescription` props to provide a description for screen readers. ```jsx live () => { const MockData = utils.useSearchInputMock(); const form = useForm(); const handleSearch = (data) => { console.log('Searched', data); }; return ( <FormProvider state={form}> <SearchInput placeholder="Search..." model="search-input-form" label="Add Input Left and Right Elements" hideLabel isClearable onClickSearchButton={() => {}} inputLeftElement={<IconSymbol icon="star" size="20px" color="$gray6" />} inputRightElement={<IconSymbol icon="check" size="20px" />} inputLeftElementDescription="Star Icon" inputRightElementDescription="Checkmark Icon" options={MockData} onSearch={handleSearch} keys={['value']} /> </FormProvider> ); }; ``` ## Label Set the `label` prop to customize the label. To hide the input label set `hideLabel` to `true`. ```jsx live () => { const MockData = utils.useSearchInputMock(); const form = useForm(); const handleSearch = (data) => { console.log('Searched', data); }; return ( <FormProvider state={form}> <Layout.Stack grow space={25}> <SearchInput label="Custom Label" placeholder="Visible Label" model="label-search" options={MockData} onSearch={handleSearch} keys={['value']} /> <SearchInput label="Custom Label" placeholder="Hidden Label" model="label-search" options={MockData} onSearch={handleSearch} hideLabel keys={['value']} /> </Layout.Stack> </FormProvider> ); }; ``` ## Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip) or a [Popover](/web/ui/popover). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live () => { const MockData = utils.useSearchInputMock(); const form = useForm(); const handleSearch = (data) => { console.log('Searched', data); }; return ( <FormProvider state={form}> <Layout.Stack grow space={25}> <SearchInput label="Default Helper" helper="This is a tooltip" model="helper-tooltip" options={MockData} onSearch={handleSearch} keys={['value']} /> <SearchInput label="Custom Helper" helper={ <Popover title="Custom Helper" content="This is a popover with a custom icon" > <IconSymbol icon="help" variant="outlined" color="$success1" size="$sm" /> </Popover> } model="helper-custom" options={MockData} onSearch={handleSearch} keys={['value']} validators={{ required: true }} /> </Layout.Stack> </FormProvider> ); }; ``` ## Subtext Use the `subText` prop to display helpful text below the search input field. ```jsx live () => { const MockData = utils.useSearchInputMock(); const form = useForm(); const handleSearch = (data) => { console.log('Searched', data); }; return ( <FormProvider state={form}> <SearchInput options={MockData} onSearch={handleSearch} isClearable keys={['value']} placeholder="Search..." label="Subtext" model="subText" subText="Custom Subtext" /> </FormProvider> ); }; ``` ## Descriptors display Use the `descriptorsDisplay` prop to set the orientation of the error message and subtext descriptor content. Available variants include 'column' and 'row'. The default is set to 'row'. Use the [FormProvider](/web/ui/form-provider#descriptors-display) and `descriptorsDisplay` to set the descriptors orientation across an entire form. Note: The errorMessage prop does not work with useForm and is only applicable within our form input components when useState is being utilized. See the [useForm Docs](/web/hooks/use-form#set-error) for example use cases with useForm. ```jsx live () => { const MockData = utils.useSearchInputMock(); const [value, setValue] = React.useState(''); const handleSearch = (data) => { console.log('Searched', data); }; return ( <SearchInput value={value} onChange={setValue} onSearch={handleSearch} onClear={() => setValue('')} isClearable options={MockData} keys={['value']} placeholder="Search..." label="Descriptors Display" subText="Subtext Message" errorMessage="Error Message" descriptorsDisplay="column" /> ); }; ``` ## Rounded Use the `rounded` prop to change the style of the `SearchInput` from squared to rounded. The default is squared and set to `false`. ```jsx live () => { const MockData = utils.useSearchInputMock(); const form = useForm(); const handleSearch = (data) => { console.log('Searched', data); }; return ( <FormProvider state={form}> <SearchInput placeholder="Search..." model="search-rounded" label="Rounded" hideLabel options={MockData} onSearch={handleSearch} keys={['value']} rounded /> </FormProvider> ); }; ``` ## openOnFocus Use the `openOnFocus` prop to open the drop-down menu when the search input field is focused. By default the menu will not open until either a value is entered into the input field or `uniqueStorageId` is used and recent searches are present. ```jsx live () => { const MockData = utils.useSearchInputMock(); const form = useForm(); return ( <FormProvider state={form}> <SearchInput placeholder="Focus to open..." model="search-input-open-on-focus" label="Open On Focus" hideLabel onClickSearchButton={() => {}} options={MockData} keys={['value']} openOnFocus /> </FormProvider> ); }; ``` ## onClickSearchButton Set the `onClickSearchButton` prop to make the spyglass clickable in the search. It gets passed a function and can be used to submit the search query. ```jsx live () => { const MockData = utils.useSearchInputMock(); const form = useForm(); const handleSearch = (data) => { console.log('Searched', data); }; return ( <FormProvider state={form}> <SearchInput resultLimit={3} label="on Click Search Button" hideLabel placeholder="Search..." model="search" options={MockData} onClickSearchButton={handleSearch} isClearable onSearch={handleSearch} keys={['value']} /> </FormProvider> ); }; ``` ## onInputChange The `onInputChange` prop is an event handler called when the value of text input changes. The callback returns both the value of the input as well a flag if the value was updated via an arrow key up or down. ```jsx live () => { const MockData = utils.useSearchInputMock(); const form = useForm(); const onInputChange = (value, isArrowKeyDown) => { console.log('value', value); console.log('isArrowKeyDown', isArrowKeyDown); }; return ( <FormProvider state={form}> <SearchInput label="on Input Change" hideLabel placeholder="Search..." model="search" options={MockData} onInputChange={onInputChange} isClearable keys={['value']} /> </FormProvider> ); }; ``` ## Disable search result items Disable an individual search result item by setting the `isDisabled` key to `true` within the object. ```jsx live () => { const MockData = [ { label: 'UnitedHealthcare Claim Estimator', value: 'UnitedHealthcare Claim Estimator', }, { label: 'UnitedHealthcare CommunityCare', value: 'UnitedHealthcare CommunityCare', isDisabled: true, }, { label: 'UnitedHealthcare Oxford', value: 'UnitedHealthcare Oxford', }, ]; const form = useForm(); const handleSearch = (data) => { console.log('Searched', data); }; return ( <FormProvider state={form}> <SearchInput label="Disabled Items" hideLabel placeholder="Search..." model="search" options={MockData} onSearch={handleSearch} keys={['value']} /> </FormProvider> ); }; ``` ## Enable outside scroll Set the `enableOutsideScroll` prop to `true` to Enable scroll outside of the search input component while the option list is open. Default is set to `false`. ```jsx live () => { const MockData = utils.useSearchInputMock(); const form = useForm(); const handleSearch = (data) => { console.log('Searched', data); }; return ( <FormProvider state={form}> <SearchInput label="Enabled Outside Scroll" hideLabel placeholder="Search..." model="search" options={MockData} onSearch={handleSearch} enableOutsideScroll /> </FormProvider> ); }; ``` ## Input default value Use the `inputDefaultValue` prop to supply a default value in the search input field on load. Once the user types into the search input, all newly entered values will apply going forward. Notes: - This should only be used in cases where on load, you're attempting to replicate the action of a user performing a search. If you want to set a selected value that pertains to an available drop-down option item, use the value prop or, if using the FormProvider, use the [defaultValues](/web/hooks/use-form#default-values) prop in the useForm hook. - Usage of this prop will also generate a filtering of the available drop-down options on load. If the [customFilter](#custom-filtering) or [apiFiltering](#api-filtering-with-debounce) props are being used, they will also be called on load. ```jsx live () => { const MockData = utils.useSearchInputMock(); const form = useForm(); const handleSearch = (data) => { console.log('Searched', data); }; const handleInputChange = (inputValue) => { console.log('Input value', inputValue); }; return ( <FormProvider state={form}> <SearchInput placeholder="Search..." label="Input Default Value" hideLabel model="search" onInputChange={handleInputChange} onSearch={handleSearch} isClearable options={MockData} inputDefaultValue="oxford" /> </FormProvider> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={SearchInput} rows={[ { name: 'placeholder', type: 'string', description: 'Description of expected value', }, { name: 'isDisabled', type: 'boolean', description: 'Flag to disable search bar', }, { name: 'isClearable', type: 'boolean', description: 'Flag to display clear button', }, { name: 'label', type: 'string', description: 'Search input label', }, { name: 'hideLabel', type: 'boolean', description: 'Flag to hide label', }, { name: 'helper', type: 'node | string', description: 'Helper element next to label', }, { name: 'subText', type: 'string', description: 'Text displayed below the search input field', }, { name: 'errorMessage', type: 'string', description: 'Error message displayed below the search input field', }, { name: 'descriptorsDisplay', type: '"row" | "column"', description: 'Set the orientation of descriptor content located below the search input field', }, { name: 'value', type: 'number | string', description: 'Value of search bar', }, { name: 'onChange', type: 'function', description: 'Callback fired every time the search value changes. The component provides two arguments to this callback: value (the new selected value) and selectedOption (an object representing the selected option properties).', }, { name: 'onInputChange', type: 'function', description: 'Callback fired when the value of the text input changes', }, { name: 'onSearch', type: 'function', description: 'Callback fired when search item is selected', }, { name: 'customFilter', type: 'function', description: 'Custom Filter used for Fuse', }, { name: 'apiFiltering', type: 'function', description: 'Api Filter used for fetching results from an api', }, { name: 'onClear', type: 'function', description: 'Callback fired every time search bar clears', }, { name: 'customRender', type: 'function', description: 'Custom render for results', }, { name: 'model', type: 'string', description: 'Unique identifier used for FormProvider', }, { name: 'width', type: 'number | string', description: 'Set width of search input', }, { name: 'height', type: 'number | string', description: 'Set height of search input', }, { name: 'uniqueStorageId', type: 'string', description: "Used to store user's recent searches", }, { name: 'options', type: 'array[object]', description: 'Data filtered on by Fuse', }, { name: 'fuseConfig', type: 'shape', description: 'Config for Fuse', }, { name: 'keys', type: 'array[string]', description: 'Keys used by Fuse', default: "['value', 'label']", }, { name: 'resultLimit', type: 'number', description: 'Set the limit of number of results', }, { name: 'debounceTime', type: 'number', description: 'Set the length of time that the search recommendations should debounce by (in milliseconds)', }, { name: 'onClickSearchButton', type: 'function', description: 'Toggles whether the spyglass for the search is a button or a decoration. The function passed determines what the spyglass will do when clicked', }, { name: 'enableOutsideScroll', type: 'boolean', default: 'false', description: 'Flag to enable scroll on all outside elements', }, { name: 'rounded', type: 'boolean', description: 'Change the search input style from squared to rounded', }, { name: 'inputLeftElement', type: 'ReactNode', description: 'Add element to left of inside search input', }, { name: 'inputRightElement', type: 'ReactNode', description: 'Add element to right of inside search input', }, { name: 'inputLeftElementDescription', type: 'string', description: 'Screen reader description for the left input element', }, { name: 'inputRightElementDescription', type: 'string', description: 'Screen reader description for the right input element', }, { name: 'openOnFocus', type: 'boolean', description: 'Drop-down menu will open on focus of search input field', }, { name: 'isLoading', type: 'boolean', description: 'Flag to display loader on search', }, { name: 'customLoader', type: 'node', description: 'Custom loader node display when isLoading is true', }, { name: 'customNoOptionsMessage', type: 'string', description: 'Custom message displayed when search returns no results', default: 'No Options', }, { name: 'inputDefaultValue', type: 'string', description: 'Add a default value to the search input field on load', }, { name: 'ref', type: 'object', description: 'Add a ref to the input element; includes clearInput method', }, { name: 'optionIcon', type: 'ReactNode', description: 'Change or remove icons present in dropdown menu options', }, { name: 'inputIcon', type: 'ReactNode', description: 'Change or remove icon present in input field', }, { name: 'validators', type: 'object', description: 'Rules for search input validation', }, { name: 'labelKey', type: 'string', description: 'Set the key value of the label in the options list. Defaults to "label"', }, { name: 'valueKey', type: 'string', description: 'Set the key value of the value in the options list. Defaults to "value"', }, { name: 'retainSectionHeader', type: 'boolean', description: 'Retains the corresponding section headers in the results when searching', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={SearchInput} rows={[ { name: 'search-input-root', description: 'Search input root element', }, { name: 'search-input-label', description: 'Search input label element', }, { name: 'search-input-input-container', description: 'Search input input container element', }, { name: 'search-input-left-element-wrapper', description: 'Wrapper for left input element', }, { name: 'search-input-left-element', description: 'Input left element', }, { name: 'search-input-right-element-wrapper', description: 'Wrapper for right input element', }, { name: 'search-input-right-element', description: 'Input right element', }, { name: 'search-input-icon-container', description: 'Search input icon container element', }, { name: 'search-input-icon', description: 'Search input icon element', }, { name: 'search-input-input', description: 'Search input input element', }, { name: 'search-input-loading-container', description: 'Search input loading container element', }, { name: 'search-input-loading-spinner', description: 'Search input loading spinner element', }, { name: 'search-input-clear', description: 'Search input clear button element', }, { name: 'search-input-element-wrapper', description: 'Search input clear/icon element wrapper', }, { name: 'search-input-descriptors', description: 'Search input descriptors element', }, { name: 'search-input-option-list', description: 'Search Input option list element', }, { name: 'search-input-no-options', description: 'Search Input no-options list element', }, { name: 'search-input-section', description: 'Search input section header option element', }, { name: 'search-input-option', description: 'Search input option element', }, { name: 'search-input-local-storage-option-container', description: 'Search input local storage option element container', }, { name: 'search-input-option-icon', description: 'Search input option icon element', }, { name: 'search-input-option-content', description: 'Search input option content element', }, { name: 'search-input-portal-container', description: 'Search input portal container element', }, ]} /> ``` </Tab> <Tab label="Accessibility"> A combobox is a widget made up of the combination of two distinct elements: 1) a single-line textbox, and 2) an associated pop-up element for helping users set the value of the textbox. The popup may be a listbox, grid, tree, or dialog. Many implementations also include a third optional element -- a graphical button adjacent to the textbox, indicating the availability of the popup. Activating the button displays the popup if suggestions are available. Adheres to the <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/combobox/">Combo box WAI-ARIA design pattern.</ExitLink>. Example: <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-both/">Editable Combobox With Both List and Inline Autocomplete</ExitLink> <h2>Include meaningful accessible labels, even when not displayed</h2> All SearchInput fields must include a meaningful label, even if hidden (using hideLabel). This should start with the word "Search" especially if there is any visible text that suggests that (such as placeholder="Search..."). ```jsx live () => { const [value, setValue] = React.useState(''); return ( <SearchInput label="Search menu" hideLabel placeholder="Search our menu..." value={value} onChange={setValue} onClear={() => setValue('')} openOnFocus fuseConfig={{ threshold: 0.1 }} retainSectionHeader options={[ { value: '1', label: 'Order for pickup only' }, { section: 'Drinks', items: [ { value: '10', label: 'Water' }, { value: '20', label: 'Soft drinks' }, ], }, { section: 'Entrees', items: [ { value: '11', label: 'Hamburger' }, { value: '21', label: 'Chicken Tenders' }, ], }, { section: 'Sides', items: [ { value: '31', label: 'French Fries' }, { value: '41', label: 'Onion Rings' }, ], }, ]} /> ); }; ``` ```jsx render <Docs.AccessibilityTable title="Textbox" rows={[ { name: 'Down Arrow', description: 'If the listbox is displayed: Moves focus to the second suggested value. Note that the first value is automatically selected. If the listbox is not displayed: opens the listbox and moves focus to the first value', }, { name: 'Up Arrow', description: 'If the listbox is displayed, moves focus to the last suggested value. If the listbox is not displayed, opens the listbox and moves focus to the last value', }, { name: 'Alt + Down Arrow', description: 'Opens the listbox without moving focus or changing selection', }, { name: 'Enter', description: 'If the listbox is displayed and the first option is automatically selected: Sets the textbox value to the content of the selected option. Closes the listbox', }, { name: 'Esc', description: 'Clears the textbox. If the listbox is displayed, closes it', }, ]} /> ``` ```jsx render <Docs.AccessibilityTable title="Listbox" rows={[ { name: 'Enter', description: 'Sets the textbox value to the content of the focused option in the listbox. Closes the listbox. Sets focus on the textbox', }, { name: 'Esc', description: 'Closes the listbox. Sets focus on the textbox. Clears the textbox', }, { name: 'Down Arrow', description: 'Moves focus to the next option. If focus is on the last option, moves focus to the first option', }, { name: 'Up Arrow', description: 'Moves focus to the previous option. If focus is on the first option, moves focus to the last option', }, { name: 'Right Arrow', description: 'Moves focus to the textbox and moves the editing cursor one character to the right', }, { name: 'Left Arrow', description: 'Moves focus to the textbox and moves the editing cursor one character to the left', }, { name: 'Home', description: 'Moves focus to the textbox and places the editing cursor at the beginning of the field', }, { name: 'End', description: 'Moves focus to the textbox and places the editing cursor at the end of the field', }, ]} /> ``` </Tab> --- id: search-results category: Data Display title: SearchResults description: Organizes the results of a search data set and displays them. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=33635-115513 --- <Tab label="Overview"> ```jsx import { SearchResults } from '@uhg-abyss/web/ui/SearchResults'; ``` ## Usage SearchResults is used for formatting search results in a UI. The `data` prop is an array containing the data that is being searched on. Each object in the array contains three fields, `id` (the title of the result), `link` (a link to the result's page), and `content` (a description of the link / result). The `id` and `content` fields are required. The `link` field is optional. The `searchTerm` prop is what will be searched on. The search is performed against the `id` field in the `data` array. ```jsx live () => { const searchResults = [ { id: 'All Savers Alternate Funding', link: 'https://www.unitedhealthgroup.com', content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum accumsan euismod dapibus. Sed volutpat ullamcorper elit, at ornare sem consectetur non. In quam diam, rhoncus eget venenatis eu, iaculis id orci. Cras sit amet lectus sollicitudin, congue lectus ut, ullamcorper tortor. Sed pretium facilisis risus, quis mollis urna pretium non.', }, { id: 'Hospital Perf-Based Comp Reports', link: 'https://www.unitedhealthgroup.com', content: 'Hospital Perf-Based Comp Reports', }, { id: 'Individual Health Record', link: 'https://www.unitedhealthgroup.com', content: 'Individual Health Record', }, { id: 'Onboard Pro', link: 'https://www.unitedhealthgroup.com', content: 'Onboard Pro', }, { id: 'Optum Behavioral Provider Express Portal', link: 'https://www.unitedhealthgroup.com', content: 'Optum Behavioral Provider Express Portal', }, { id: 'Physician Performance & Reporting', link: 'https://www.unitedhealthgroup.com', content: 'Physician Performance & Reporting', }, { id: 'Practice Assist', link: 'https://www.unitedhealthgroup.com', content: 'Practice Assist', }, { id: 'Test Registry', link: 'https://www.unitedhealthgroup.com', content: 'Test Registry', }, { id: 'UnitedHealthcare Claim Estimator', link: 'https://www.unitedhealthgroup.com', content: 'UnitedHealthcare Claim Estimator', }, { id: 'UnitedHealthcare CommunityCare', link: 'https://www.unitedhealthgroup.com', content: 'UnitedHealthcare CommunityCare', }, { id: 'UnitedHealthcare Oxford', link: 'https://www.unitedhealthgroup.com', content: 'Praesent laoreet eget turpis euismod feugiat. Fusce sodales diam vitae lectus aliquet vehicula. Duis lobortis posuere mauris, quis blandit velit gravida ut. Proin massa metus, pellentesque eu egestas sit amet, tristique quis enim.', }, { id: 'UnitedHealthcare Practice Facility Profile', link: 'https://www.unitedhealthgroup.com', content: 'UnitedHealthcare Practice Facility Profile', }, { id: 'UnitedHealthcare Reports', link: 'https://www.unitedhealthgroup.com', content: 'UnitedHealthcare Reports', }, { id: 'UnitedHealthcare West Reports', link: 'https://www.unitedhealthgroup.com', content: 'UnitedHealthcare West Reports', }, { id: 'VACCN', link: 'https://www.unitedhealthgroup.com', content: 'Proin massa metus, pellentesque eu egestas sit amet, tristique quis enim.', }, { id: 'AARP Provider Online Tool', link: 'https://www.unitedhealthgroup.com', content: 'AARP Provider Online Tool', }, { id: 'CAQH ProView™', link: 'https://www.unitedhealthgroup.com', content: 'CAQH ProView™', }, { id: 'Care Conductor and Notification of Pregnancy', link: 'https://www.unitedhealthgroup.com', content: 'Care Conductor and Notification of Pregnancy', }, { id: 'Claims Submission', link: 'https://www.unitedhealthgroup.com', content: 'Claims Submission', }, { id: 'Cover My Meds', link: 'https://www.unitedhealthgroup.com', content: 'Cover My Meds', }, { id: 'UHC Dental DSNP & Medicaid ', link: 'https://www.unitedhealthgroup.com', content: 'UHC Dental DSNP & Medicaid ', }, { id: 'Dental Benefit Providers UHC C&S', link: 'https://www.unitedhealthgroup.com', content: 'Dental Benefit Providers UHC C&S', }, { id: 'HBMA Find a Medical Biller', link: 'https://www.unitedhealthgroup.com', content: 'HBMA Find a Medical Biller', }, { id: 'Health Plan of Nevada', link: 'https://www.unitedhealthgroup.com', content: 'Health Plan of Nevada', }, { id: 'InstaMed Member Payments', link: 'https://www.unitedhealthgroup.com', content: 'InstaMed Member Payments', }, { id: 'Medical Billing Education', link: 'https://www.unitedhealthgroup.com', content: 'Medical Billing Education', }, { id: 'Office Ally', link: 'https://www.unitedhealthgroup.com', content: 'Office Ally', }, { id: 'Optum Physical Health', link: 'https://www.unitedhealthgroup.com', content: 'Optum Physical Health', }, { id: 'Secure Messenger Clinical Data Submission', link: 'https://www.unitedhealthgroup.com', content: 'Secure Messenger Clinical Data Submission', }, { id: 'Spectera Vision Providers', link: 'https://www.unitedhealthgroup.com', content: 'Spectera Vision Providers', }, { id: 'UMR', link: 'https://www.unitedhealthgroup.com', content: 'UMR', }, { id: 'UnitedHealth One', link: 'https://www.unitedhealthgroup.com', content: 'UnitedHealth One', }, { id: 'UnitedHealth Premium United in Care', link: 'https://www.unitedhealthgroup.com', content: 'UnitedHealth Premium United in Care', }, { id: 'UnitedHealthcare Claims Research Project', link: '/claims/research', content: 'UnitedHealthcare Claims Research Project', }, { id: 'UHC Insights', link: 'https://www.unitedhealthgroup.com', content: 'UHC Insights', }, { id: 'Dental Xchange', link: 'https://www.unitedhealthgroup.com', content: 'Dental Xchange', }, { id: 'Paperless Delivery Options', link: 'https://www.unitedhealthgroup.com', content: 'Paperless Delivery Options', }, { id: 'UnitedHealthcare OneNet PPO Pricing', link: 'https://www.unitedhealthgroup.com', content: 'UnitedHealthcare OneNet PPO Pricing', }, { id: 'Document Vault - Electronic Letters & Reports', link: '/documentlibrary', content: 'Document Vault - Electronic Letters & Reports', }, { id: 'EPS / Optum Pay', link: 'https://www.unitedhealthgroup.com', content: 'EPS / Optum Pay', }, { id: 'My Practice Profile', link: 'https://www.unitedhealthgroup.com', content: 'My Practice Profile', }, { id: 'Eligibility', link: '/eligibility', content: 'Eligibility', }, { id: 'Claims', link: '/claims', content: 'Claims', }, { id: 'PAAN', link: 'https://www.unitedhealthgroup.com', content: 'PAAN', }, { id: 'Referrals', link: '/referrals', content: 'Referrals', }, { id: 'Direct Connect', link: 'https://www.unitedhealthgroup.com', content: 'Direct Connect', }, { id: 'Optum Intelligent EDI', link: 'https://www.unitedhealthgroup.com', content: 'Optum Intelligent EDI', }, { id: 'Optum VA Community Care Network', link: 'https://www.unitedhealthgroup.com', content: 'Optum VA Community Care Network', }, { id: 'Patterns of Care', link: 'https://www.unitedhealthgroup.com', content: 'Patterns of Care', }, { id: 'PreCheck MyScript', link: 'https://www.unitedhealthgroup.com', content: 'PreCheck MyScript', }, { id: 'Remote EMR access', link: 'https://www.unitedhealthgroup.com', content: 'Remote EMR access', }, { id: 'UnitedHealthcare Fee Schedule Lookup', link: 'https://www.unitedhealthgroup.com', content: 'UnitedHealthcare Fee Schedule Lookup', }, { id: 'Jade', link: 'https://www.unitedhealthgroup.com', content: 'Jade', }, { id: 'NC Virtual Health', link: 'https://www.unitedhealthgroup.com', content: 'NC Virtual Health', }, { id: 'UNAS', link: 'https://www.unitedhealthgroup.com', content: 'UNAS', }, { id: 'Specialty Management Access Portal', link: 'https://www.unitedhealthgroup.com', content: 'Specialty Management Access Portal', }, { id: 'Med Therapy Management', link: 'https://www.unitedhealthgroup.com', content: 'Med Therapy Management', }, { id: 'UHOne', link: 'https://www.unitedhealthgroup.com', content: 'UHOne', }, { id: 'Health Plan of NV', link: 'https://www.unitedhealthgroup.com', content: 'Health Plan of NV', }, ]; return <SearchResults data={searchResults} searchTerm="united" />; }; ``` ## Pagination The `pageSize` prop can be used to specify the number of results that appear on each page. The default value is `10`. ```jsx live () => { const searchResults = [ { id: 'UnitedHealthcare OneNet PPO Pricing', link: 'https://www.unitedhealthgroup.com', content: 'UnitedHealthcare OneNet PPO Pricing', }, { id: 'UnitedHealth One', link: 'https://www.unitedhealthgroup.com', content: 'UnitedHealth One', }, { id: 'UnitedHealth Premium United in Care', link: 'https://www.unitedhealthgroup.com', content: 'UnitedHealth Premium United in Care', }, { id: 'UnitedHealthcare Claims Research Project', link: '/claims/research', content: 'UnitedHealthcare Claims Research Project', }, { id: 'UnitedHealthcare Practice Facility Profile', link: 'https://www.unitedhealthgroup.com', content: 'UnitedHealthcare Practice Facility Profile', }, { id: 'UnitedHealthcare Reports', link: 'https://www.unitedhealthgroup.com', content: 'UnitedHealthcare Reports', }, { id: 'UnitedHealthcare West Reports', link: 'https://www.unitedhealthgroup.com', content: 'UnitedHealthcare West Reports', }, ]; return ( <SearchResults data={searchResults} searchTerm="united" pageSize={2} /> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={SearchResults} rows={[ { name: 'data', type: 'array[object]', description: 'Data used to compute search', }, { name: 'searchTerm', type: 'string', description: 'Search term used in search', }, { name: 'pageSize', type: 'number', description: 'Set the size of page', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={SearchResults} rows={[ { name: 'search-result-root', description: 'Search result root element', }, { name: 'search-result-label', description: 'Label', }, { name: 'search-result-container', description: 'Container', }, { name: 'search-result-list', description: 'Results list', }, { name: 'search-result-item', description: 'Result item', }, ]} /> ``` </Tab> --- id: segmented-controls-v2 category: Content title: V2SegmentedControls description: Combines radio buttons and tabs to give multiple options as one element. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=10551-18607 subDirectory: SegmentedControls sourceIsTS: true --- <Tab label="Overview"> ```jsx import { V2SegmentedControls } from '@uhg-abyss/web/ui/SegmentedControls'; ``` ```jsx sandbox { component: 'V2SegmentedControls', inputs: [ { prop: 'fullWidth', type: 'boolean' }, ] } () => { const [activeTab, setActiveTab] = useState('opt-2'); const InnerText = ({ activeTab }) => ( <V2Card> <Label>This is the content for {activeTab}</Label> <Text> Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt. </Text> </V2Card> ); return ( <V2SegmentedControls value={activeTab} onChange={setActiveTab} title="Options"> <V2SegmentedControls.Tab label="Option 1" value="opt-1"> <InnerText activeTab={activeTab} /> </V2SegmentedControls.Tab> <V2SegmentedControls.Tab label="Option 2" value="opt-2"> <InnerText activeTab={activeTab} /> </V2SegmentedControls.Tab> <V2SegmentedControls.Tab label="Option 3" value="opt-3"> <InnerText activeTab={activeTab} /> </V2SegmentedControls.Tab> <V2SegmentedControls.Tab label="Option 4" value="opt-4"> <InnerText activeTab={activeTab} /> </V2SegmentedControls.Tab> <V2SegmentedControls.Tab label="Option 5" value="opt-5"> <InnerText activeTab={activeTab} /> </V2SegmentedControls.Tab> </V2SegmentedControls> ); }; ``` ## Controlled (value + onChange) Use the `value` and `onChange` props to control the active tab state externally. This approach is useful when you need to manage the tab state within your component or through an external state management solution. - `value`: Specifies the currently active tab. - `onChange`: Callback function that handles tab changes. ```jsx live () => { const [activeTab, setActiveTab] = useState('Option 1'); return ( <V2SegmentedControls value={activeTab} onChange={setActiveTab} title="Options" fullWidth > <V2SegmentedControls.Tab label="Option 1" value="Option 1"> <V2Card> <Label>This is the content for {activeTab}</Label> </V2Card> </V2SegmentedControls.Tab> <V2SegmentedControls.Tab label="Option 2" value="Option 2"> <V2Card> <Label>This is the content for {activeTab}</Label> </V2Card> </V2SegmentedControls.Tab> <V2SegmentedControls.Tab label="Option 3" value="Option 3"> <V2Card> <Label>This is the content for {activeTab}</Label> </V2Card> </V2SegmentedControls.Tab> <V2SegmentedControls.Tab label="Option 4" value="Option 4"> <V2Card> <Label>This is the content for {activeTab}</Label> </V2Card> </V2SegmentedControls.Tab> </V2SegmentedControls> ); }; ``` ## Uncontrolled (initialValue) In cases where you don't need to control the active tab state, you can use the `initialValue` prop to specify which tab should be active by default when the component loads. This eliminates the need to use the `value` and `onChange` props for managing the active tab state externally. ```jsx live () => { return ( <Layout.Stack space={16} grow> <V2SegmentedControls fullWidth initialValue="Option 1" title="Options"> <V2SegmentedControls.Tab label="Option 1" value="Option 1"> <V2Card> <Label>This is the content for "Option 1"</Label> </V2Card> </V2SegmentedControls.Tab> <V2SegmentedControls.Tab label="Option 2" value="Option 2"> <V2Card> <Label>This is the content for "Option 2"</Label> </V2Card> </V2SegmentedControls.Tab> <V2SegmentedControls.Tab label="Option 3" value="Option 3"> <V2Card> <Label>This is the content for "Option 3"</Label> </V2Card> </V2SegmentedControls.Tab> <V2SegmentedControls.Tab label="Option 4" value="Option 4"> <V2Card> <Label>This is the content for "Option 4"</Label> </V2Card> </V2SegmentedControls.Tab> </V2SegmentedControls> </Layout.Stack> ); }; ``` ## Title The `title` property provides a label that describes the purpose of the set of controls (tabs). This is a required property, as it gives screen reader users important context. ## Full width The `fullWidth` prop (optional), when set to true, makes the component take all the available horizontal space of its parent container. ## Label (individual tab) The`label` prop (required) is used to define the display in each Tab. ## Tab icon (individual tab) To insert an [IconSymbol](/web/ui/icon-symbol) into each tab, use the `tabIcon` prop. It accepts either a string (the name of the IconSymbol to use) or an object of the following type: ```ts { icon: string; variant: 'filled' | 'outlined'; } ``` ```jsx live () => { return ( <V2SegmentedControls initialValue="Option 1" title="Options"> <V2SegmentedControls.Tab label="Home" value="Option 1" tabIcon={{ icon: 'home', variant: 'outlined' }} > <V2Card> <Label>This is the content for "Home"</Label> </V2Card> </V2SegmentedControls.Tab> <V2SegmentedControls.Tab label="Settings" value="Option 2" tabIcon={{ icon: 'settings', variant: 'filled' }} > <V2Card> <Label>This is the content for "Settings"</Label> </V2Card> </V2SegmentedControls.Tab> <V2SegmentedControls.Tab label="Calendar" value="Option 3" tabIcon="calendar_month" > <V2Card> <Label>This is the content for "Calendar"</Label> </V2Card> </V2SegmentedControls.Tab> <V2SegmentedControls.Tab label="Language" value="Option 4" tabIcon="language" > <V2Card> <Label>This is the content for "Language"</Label> </V2Card> </V2SegmentedControls.Tab> </V2SegmentedControls> ); }; ``` ## Tabbable content Use the `tabbableContent` prop within the `V2SegmentedControls.Tab` component to control the user's ability to tab-key focus the content container. `tabbableContent` is set to `true` by default. This prop is useful for addressing possible [accessibility concerns](/web/ui/segmented-controls-v2?tab=accessibility). ```jsx live () => { const [activeTab, setActiveTab] = useState('Option 1'); return ( <V2SegmentedControls value={activeTab} onChange={setActiveTab} title="Options" > <V2SegmentedControls.Tab label="Option 1" value="Option 1" tabbableContent={false} > <V2Card> <Label>Can't focus content with tab key</Label> </V2Card> </V2SegmentedControls.Tab> <V2SegmentedControls.Tab label="Option 2" value="Option 2"> <V2Card> <Label>Can focus content with tab key</Label> </V2Card> </V2SegmentedControls.Tab> </V2SegmentedControls> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2SegmentedControls" propTypeName="SegmentedControlsProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="V2SegmentedControls.Tab" propTypeName="SegmentedControlsTabProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2ClassesTable title="V2SegmentedControls" classes={[SegmentedControlsClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2SegmentedControls.Tab" classes={[SegmentedControlsTabClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> V2SegmentedControls at its core functions as a "tabbing" system, similar to simple navigation menu, where no more than one of the buttons can be checked at a time. The `title` prop is required to provide context for screen readers. Use the `ariaLabel` prop in `V2SegmentedControls.Tab` when using abbreviated words. This will include an "aria-label" for screen readers. Adheres to the <ExitLink href="https://www.w3.org/TR/wai-aria-practices-1.2/#toggletabs"> WAI-ARIA design pattern</ExitLink>. ```jsx live () => { const [activeTab, setActiveTab] = useState('Calendar'); const innerCard = (activeTab) => ( <V2Card> <Label>{activeTab} tabpanel</Label> <Text> <p> This is the generic content for the "{activeTab}" tabpanel. The assumption is that this tabpanel will be a major mode on the screen. This example is similar to that of MS Outlook on an iPad. </p> <p> Another assumption is all tabpanels will have at least one focusable element. Otherwise, like{' '} <V2Link href="https://abyss.uhc.com/web/ui/tabs-v2?tab=overview"> V2Tabs </V2Link> , it will need a prop to set focus to the entire tabpanel itself. </p> </Text> </V2Card> ); return ( <Layout.Stack space={16} grow> <V2SegmentedControls value={activeTab} onChange={setActiveTab} title="Control center" > <V2SegmentedControls.Tab label="Email" value="Email"> {innerCard(activeTab)} </V2SegmentedControls.Tab> <V2SegmentedControls.Tab label="Calendar" value="Calendar"> {innerCard(activeTab)} </V2SegmentedControls.Tab> <V2SegmentedControls.Tab label="To dos" value="To dos"> {innerCard(activeTab)} </V2SegmentedControls.Tab> <V2SegmentedControls.Tab label="Chats" value="Chats"> {innerCard(activeTab)} </V2SegmentedControls.Tab> </V2SegmentedControls> </Layout.Stack> ); }; ``` <h3> Reduced Motion </h3> Animations and transitions that have been changed when a user has `prefers-reduced-motion` set to `reduced`: - Removed animation of active background color upon switching tabs ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Tab', description: 'Moves focus to the active tab', }, { name: 'Space', description: 'Selects the currently focused tab', }, { name: 'Enter', description: 'Selects the currently focused tab', }, { name: 'Arrow Right', description: 'Moves focus to the next tab in the group.', }, { name: 'Arrow Left', description: 'Moves focus to the previous tab in the group.', }, { name: 'Home', description: 'When focused on the active tab, moves focus to the first tab.', }, { name: 'End', description: 'When focused on the active tab, moves focus to the last tab.', }, ]} /> ``` </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={V2SegmentedControls} keys={['segmentedControlsV2']} /> ``` </Tab> --- id: select-input-multi-v2 category: Forms title: V2SelectInput (Multi) description: Allows users to select multiple values from a provided list of options. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=10412-6930 sourcePath: ui/SelectInput/v2/V2SelectInput.tsx --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="SelectInputMulti"></Docs.V2MigrationBanner> ``` ```jsx import { V2SelectInput } from '@uhg-abyss/web/ui/SelectInput'; ``` ```jsx sandbox { component: 'V2SelectInput', inputs: [ { prop: 'label', type: 'string', }, { prop: 'subText', type: 'string', }, { prop: 'width', type: 'string', }, { prop: 'hideLabel', type: 'boolean', }, { prop: 'isClearable', type: 'boolean', }, { prop: 'isDisabled', type: 'boolean', }, { prop: 'isSearchable', type: 'boolean', }, ], } () => { const [value, setValue] = React.useState(['alpine']); const onSubmit = () => { console.log('value', value); }; return ( <React.Fragment> <V2SelectInput isMulti label="Your favorite framework/library" value={value} onChange={setValue} isClearable isSearchable options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> <V2Button onClick={onSubmit} css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }}> Submit </V2Button> </React.Fragment> ); }; ``` ## Usage ### Multi-select To switch to multi-select mode, set the `isMulti` prop to `true`. This allows users to select multiple values from the provided list of options. ### Options Use the `options` prop to supply the drop-down menu options that will be available for selection. `options` is an array of objects, where each object has a base that includes the following properties: - `value`: unique identifier for the option - `label`: content the option will display within the menu list ```jsx [ { value: 'id1', label: 'Option 1' }, { value: 'id2', label: 'Option 2' }, { value: 'id3', label: 'Option 3' }, ... ] ``` Sections can also be specified. See [Section Headers](#section-headers) for more details. ### valueKey / labelKey If your data structure uses different property names than `value` and `label`, you can map them using the `valueKey` and `labelKey` props without restructuring your data. - `valueKey`: Specifies which property to use as the option's value (defaults to `"value"`) - `labelKey`: Specifies which property to use as the option's display text (defaults to `"label"`) This is particularly useful when working with API responses or existing data structures that can't be easily transformed. ```jsx live-in-view () => { const form = useFormV2(); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2SelectInput isMulti label="Label/Value Keys" model="keys" isClearable options={[ { name: 'Custom Option 1', id: 'a1' }, { name: 'Custom Option 2', id: 'b2' }, { name: 'Custom Option 3', id: 'c3' }, ]} labelKey="name" valueKey="id" /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ## Form integration ### useFormV2 (recommended) ```jsx render <Docs.FormMessage /> ``` <br /> ```jsx render <Docs.FormDisclaimer /> ``` ```jsx live-in-view () => { const form = useFormV2({ defaultValues: { selectForm: ['react'], }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2SelectInput isMulti label="SelectInput useForm" model="selectForm" isClearable isSearchable onBlur={(e) => console.log('on blur form', e.target.value)} onFocus={(e) => console.log('on focus form', e.target.value)} options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} validators={{ required: true }} /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ### useState Using the `useState` hook gets values from the component state. ```jsx live-in-view () => { const [value, setValue] = React.useState(['alpine']); const onSubmit = () => { console.log('value', value); }; const onChange = (newValue, selectedOptions) => { console.log('onChange newValue:', newValue); console.log('onChange selectedOptions', selectedOptions); setValue(newValue); }; return ( <React.Fragment> <V2SelectInput isMulti label="SelectInput useState" value={value} onChange={onChange} onBlur={(e) => console.log('on blur state', e.target.value)} onFocus={(e) => console.log('on focus state', e.target.value)} isClearable isSearchable options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> <V2Button onClick={onSubmit} css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </React.Fragment> ); }; ``` ## Display properties ### Label The `label` prop is required. The `hideLabel` prop can be set to `true` to hide the label visually, but still allow it to be accessible to screen readers. ```jsx live-in-view () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <FormSpacing> <V2SelectInput isMulti label="Active Label" model="activeLabel" options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> <V2SelectInput isMulti label="Hidden Label" model="hiddenLabel" hideLabel css={{ 'abyss-select-input-root': { marginTop: '15px' } }} options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> </FormSpacing> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ### Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip-v2) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip-v2) or a [Popover](/web/ui/popover-v2). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip-v2/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live-in-view () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); const onSubmit = (data) => { console.log('data', data); }; const options = [ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <FormSpacing> <V2SelectInput isMulti label="Default Helper" helper="This is a tooltip" model="helper-tooltip" options={options} /> <V2SelectInput isMulti label="Custom Helper" helper={ <V2Popover title="Custom Helper" content="This is a popover with a custom icon" > <IconSymbol icon="help" variant="outlined" color="$success1" size="$md" /> </V2Popover> } model="helper-custom" options={options} validators={{ required: true }} /> </FormSpacing> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ### Subtext Use the `subText` prop to display helpful information related to the input field. The prop accepts either a string or an object of the form: ```ts { text: string; position: 'above' | 'below'; } ``` The `position` property determines where the subtext will be displayed in relation to the input field. The default value is `'below'`. ```jsx live-in-view () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2({ defaultValues: { subText: ['1'], subText2: ['2'], }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <FormSpacing> <V2SelectInput isMulti label="SubText" subText={{ text: 'Subtext passed above the input', position: 'above', }} model="subText" validators={{ required: true }} options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> <V2SelectInput isMulti label="SubText" subText="Regular Subtext" model="subText2" validators={{ required: true }} options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> </FormSpacing> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ### Width Use the `width` prop to set the width of the select list. ```jsx live-in-view () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <FormSpacing> <V2SelectInput isMulti label="Default Width" model="widthDefault" isClearable options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> <V2SelectInput isMulti label="Width 75%" width="75%" model="width75" isClearable options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> <V2SelectInput isMulti label="Width" width="300px" model="width300" isClearable options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> </FormSpacing> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ### Left element Use the `inputLeftElement` prop to add an element inside of the text input field. The recommended usage is for inserting icons. The prop accepts an object with the following properties: - `element`: The element to be displayed inside the input field. - `description`: An optional string that describes the purpose of the element for screen readers. These are considered decorative and do not need to be exposed to screen readers. That said, please note that icons should _not_ provide any information that is not also conveyed in a screen-readable way. For example, an exclamation mark (!) icon to indicate errors needs to be accompanied by `aria-invalid`. If the icon is used to convey additional information, use the `inputLeftElement.description` prop to provide a description for screen readers. ```jsx live () => { const form = useFormV2({}); return ( <V2FormProvider state={form}> <V2SelectInput isMulti label="Left Element" model="leftElement" isClearable inputLeftElement={{ element: ( <IconSymbol icon="language" size="$web.semantic.sizing.icon.utility.sm" color="$input-v2.color.icon.content" /> ), description: 'Language Icon', }} options={[ { label: 'English', value: '1' }, { label: 'Spanish', value: '2' }, { label: 'German', value: '3' }, ]} /> </V2FormProvider> ); }; ``` ## Validation ### Validators (useFormV2) ```jsx render <Docs.FormCompatibilityWidget useForm /> ``` Use the `validators` prop to set rules for the field to be valid. Note: The default error message when `required` is `true` is minimally acceptable for accessibility. It is highly recommended to customize it to be more specific to the use of the field and form. ```jsx live-in-view () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); const onSubmit = (data) => { console.log('data', data); }; const options = [ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, { label: 'Option 4', value: '4' }, { label: 'Option 5', value: '5' }, ]; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <FormSpacing> <V2SelectInput isMulti label="Required Default Message" model="required" isSearchable options={options} validators={{ required: true }} /> <V2SelectInput isMulti label="Required Custom Message" model="custom-required" isSearchable options={options} validators={{ required: 'Custom Error Message' }} /> <V2SelectInput isMulti label="Custom Validators" model="validate" isSearchable options={options} validators={{ required: true, validate: { moreThanTwo: (v) => { return ( v.length >= 2 || 'Should include a minimum of two selections' ); }, }, }} /> </FormSpacing> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ### Error message (useState) ```jsx render <Docs.FormCompatibilityWidget useState /> ``` Use the `errorMessage` prop to display a custom error message below the select field when using `useState`. ```jsx live-in-view () => { const [value, setValue] = useState([]); return ( <V2SelectInput isMulti label="Error Message" value={value} onChange={setValue} options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} errorMessage="Custom Error Message" /> ); }; ``` ### Success message ```jsx render <Docs.FormCompatibilityWidget useForm useState /> ``` Use the `successMessage` prop to display a custom success message below the input field. To provide a single success message across all form input components using `useFormV2`/`V2FormProvider`, you can provide `successMessage` to `V2FormProvider` as shown [here](/web/ui/form-provider-v2#successmessage). ```jsx live-in-view () => { const form = useFormV2(); const onSubmit = (data) => { // Do something on submit console.log(data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2SelectInput isMulti label="Success Message (useForm)" model="success-message" options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} successMessage="Selection is successful" validators={{ required: 'Selection is required', }} /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ```jsx live-in-view () => { const inputRef = useRef(null); const [value, setValue] = useState(''); const [isSubmitted, setIsSubmitted] = useState(false); const [errorMessage, setErrorMessage] = useState(''); const [successMessage, setSuccessMessage] = useState(''); const validate = () => { if (!value.length) { setErrorMessage('Selection is required'); setSuccessMessage(''); inputRef.current.focus(); } else { setErrorMessage(''); setSuccessMessage('Selection is successful'); } }; const onSubmit = (e) => { e.preventDefault(); setIsSubmitted(true); validate(); }; useEffect(() => { if (isSubmitted) { validate(); } }, [value]); return ( <form onSubmit={onSubmit}> <V2SelectInput isMulti label="Success Message (useState)" value={value} onChange={setValue} isClearable ref={inputRef} options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} errorMessage={errorMessage} successMessage={successMessage} /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </form> ); }; ``` ### Highlighted ```jsx render <Docs.FormCompatibilityWidget useForm useState /> ``` Use the `highlighted` prop to enable the background color for the input. You can use `FormProvider` and `highlighted` to enable the color to appear if validation is required. ```jsx live-in-view () => { const [value, setValue] = useState(); return ( <V2SelectInput isMulti label="Your favorite framework/library" value={value} onChange={setValue} isClearable isSearchable highlighted options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> ); }; ``` ### Validation below menu ```jsx render <Docs.FormCompatibilityWidget useForm useState /> ``` Set the `validationBelowMenu` prop to `true` to relocate the error and success message validation to below the menu, when open. The default is `false` and the validation message will always remain displayed below the selection container, even when the menu is open. ```jsx live-in-view () => { const [value, setValue] = useState(); return ( <V2SelectInput isMulti label="Validation Below Menu" value={value} onChange={setValue} isClearable isSearchable errorMessage="Error Message" subText="Subtext" validationBelowMenu options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> ); }; ``` ```jsx live-in-view () => { const form = useFormV2(); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit} highlighted> <V2SelectInput isMulti label="Your favorite framework/library" model="framework" isClearable isSearchable options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} validators={{ required: true }} /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ## Interactivity ### Clearable Use the `isClearable` prop to allow for clearable select lists. If `true`, a clear button will appear in the input. The optional `onClear` callback prop can be used to trigger additional actions when the clear button is clicked. ```jsx live-in-view () => { const form = useFormV2({ defaultValues: { isClearableForm: ['1'], }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2SelectInput isMulti label="Clearable (with useForm)" model="isClearableForm" onClear={() => console.log('selections cleared')} isClearable options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> </V2FormProvider> ); }; ``` ```jsx live-in-view () => { const [value, setValue] = React.useState(['1']); return ( <V2SelectInput isMulti label="Clearable (with useState)" value={value} onChange={setValue} isClearable options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> ); }; ``` ### Select all By setting the `selectAll` property to `true`, you can make a "Select All" option visible at the top of the dropdown. When selected, all options will be selected. When deselected, all options will be deselected. ```jsx live () => { const [value, setValue] = React.useState(['alpine']); const onSubmit = () => { console.log('value', value); }; return ( <React.Fragment> <V2SelectInput isMulti label="Your favorite framework/library" value={value} onChange={setValue} selectAll isSearchable options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> <V2Button onClick={onSubmit} css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </React.Fragment> ); }; ``` ### Disabled Set the `isDisabled` prop to `true` to disable the select list input field, so users cannot select a value. ```jsx live-in-view () => { const form = useFormV2(); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2SelectInput isMulti label="Disabled" model="disabled" options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} isDisabled /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ### Enable outside scroll Set the `enableOutsideScroll` prop to `true` to enable scrolling outside the search input component while the option list is open. Default is set to `false`. ```jsx live-in-view () => { const [value, setValue] = React.useState(['alpine']); const onSubmit = () => { console.log('value', value); }; return ( <React.Fragment> <V2SelectInput isMulti label="Your favorite framework/library" value={value} onChange={setValue} isClearable isSearchable options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} enableOutsideScroll /> <V2Button onClick={onSubmit} css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </React.Fragment> ); }; ``` ## Search filtering Use the `isSearchable` prop to add an input field within the drop-down menu for the user to search/filter the list of options. ```jsx live-in-view () => { const form = useFormV2(); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2SelectInput isMulti label="Searchable" model="searchable" isSearchable options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ### Fuse.js When `isSearchable` is true, the component utilizes the <ExitLink href="https://fusejs.io">Fuse.js</ExitLink> library to implement fuzzy searching. The following sections describe how to customize the Fuse configuration using the `searchConfig` prop. ```jsx live-in-view () => { const form = useFormV2(); return ( <V2FormProvider state={form}> <V2SelectInput isMulti model="search" label="Fuse Default Search" isClearable isSearchable options={[ { value: 'react', label: 'React', }, { value: 'ng', label: 'Angular', }, { value: 'svelte', label: 'Svelte', }, { value: 'preact', label: 'Preact', }, ]} /> </V2FormProvider> ); }; ``` ### Fuse keys The `keys` prop allows you to specify the values from the specific keys within your `options` object to search against. This feature accommodates nested paths, prioritizes certain fields with weighted search, and can handle searches within arrays of objects. The default search keys are `['label', 'value']`. For example, if the `options` contained objects of the following structure: ```ts { value: "react", label: "React", tags: ['jsx', 'virtual dom', 'facebook'] } ``` and you wanted to allow users to search on the label and tags values, you would provide the following, as in the example below: ```tsx searchConfig={{ keys: ['label', 'tags'] }} ``` ```jsx live-in-view () => { const form = useFormV2({}); return ( <V2FormProvider state={form}> <V2SelectInput isMulti label="Fuse Keys Search" searchConfig={{ keys: ['label', 'tags'] }} model="framework" isClearable isSearchable options={[ { value: 'react', label: 'React', tags: ['jsx', 'virtual dom', 'facebook'], }, { value: 'ng', label: 'Angular', tags: ['typescript', 'directives', 'google'], }, { value: 'svelte', label: 'Svelte', tags: ['compile-time', 'no virtual dom', 'rich harris'], }, ]} /> </V2FormProvider> ); }; ``` ### Custom Fuse configurations The Fuse configuration can be customized by following the <ExitLink href="https://fusejs.io/api/options.html">Fuse documentation</ExitLink> and passing the configurations into the `searchConfig` prop. For example, if you wanted to adjust the <ExitLink href="https://www.fusejs.io/api/options.html#threshold">threshold</ExitLink> to `0`, thus requiring an exact match, you would pass in the following object. The default threshold is `0.1`. ```tsx const customFuseConfig = { threshold: 0, // exact match }; ``` ```jsx live-in-view () => { const [sliderValue, setSliderValue] = useState(0.0); const form = useFormV2(); const customFuseConfig = { threshold: sliderValue, keys: ['label'], }; const marksConfig = { marks: [ { value: 0.0, label: 'Exact Match' }, { value: 0.2, label: '.2' }, { value: 0.4, label: '.4' }, { value: 0.6, label: '.6' }, { value: 0.8, label: '.8' }, { value: 1.0, label: 'Match Anything' }, ], }; return ( <V2FormProvider state={form}> <Layout.Stack grow> <V2SelectInput isMulti label="Custom Fuse Threshold Config" model="framework" isClearable isSearchable searchConfig={customFuseConfig} options={[ { value: 'react', label: 'React', }, { value: 'ng', label: 'Angular', }, { value: 'svelte', label: 'Svelte', }, { value: 'preact', label: 'Preact', }, ]} /> <V2Slider label="Search Threshold" subText="Adjust the slider to change the Fuse threshold value" marksConfig={marksConfig} minValue={0.0} maxValue={1.0} value={sliderValue} onChange={setSliderValue} step={0.2} highlighted /> </Layout.Stack> </V2FormProvider> ); }; ``` ### Highlighted search results By default, when searching, the matching text within all search results will be highlighted and the font weight will be updated based on the following criteria: - not selected: the matching text displays as bold - selected: the matching text displays as regular To override this behavior and turn off the highlighting, set the `highlightMatches` prop to `false`. ```jsx live-in-view () => { const [highlightMatches, setHighlightMatches] = useState(true); const form = useFormV2(); return ( <React.Fragment> <V2FormProvider state={form}> <V2SelectInput isMulti label="Highlighted Search Results" model="framework" isClearable isSearchable highlightMatches={highlightMatches} options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'preact', label: 'Preact' }, ]} /> </V2FormProvider> <V2Button onClick={() => setHighlightMatches(!highlightMatches)} css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > {highlightMatches ? 'Disable' : 'Enable'} Search Highlighting </V2Button> </React.Fragment> ); }; ``` ### API filtering with debounce To override the Fuse filtering and make asynchronous calls to an API to set the list of dropdown options, use a combination of the `onInputChange`, `options`, and `isLoading` props. While searching, `onInputChange` will supply the current search value and the value of the current selections. `isLoading` controls the built-in loading spinner. After retrieving the option items from the API, pass them into the `options` prop. To incorporate debouncing into the search, use the `useDebounce` hook. ```jsx import { useDebounce } from '@uhg-abyss/web/hooks/useDebounce'; ``` When using debounce, it is recommended to use the `customNoOptionsMessage` prop to control the display message when there are no options available and/or when no search results are found. This example shows all of these concepts together. The apiFilter function is called on every keystroke, but the API call is debounced to only occur after 600ms of inactivity. Search "united" to see the API call in action. ```jsx live-in-view () => { const noOptionsMessage = 'No options'; const [searchMessage, setSearchMessage] = useState(noOptionsMessage); const [results, setResults] = useState([]); const [loading, setLoading] = useState(false); const form = useFormV2(); const apiFilter = (searchValue, selectedValues) => { console.log('searchValue', searchValue); console.log('selectedValues', selectedValues); if (!searchValue) { setSearchMessage(noOptionsMessage); setResults([]); return; } setLoading(true); utils.useSearchInputMockApi(searchValue).then((response) => { setLoading(false); if (response.length === 0) { setSearchMessage(`No results found for ${searchValue}`); } console.log({ results, response }); setResults(response); }); }; const debouncedApiFilter = useDebounce(apiFilter, 600); // function, delay (ms) return ( <V2FormProvider state={form}> <V2SelectInput isMulti model="apiFiltering" label="API Filtering" isSearchable highlightMatches={false} customNoOptionsMessage={searchMessage} onInputChange={debouncedApiFilter} options={results} isLoading={loading} /> </V2FormProvider> ); }; ``` ## Menu option configurations ### Disable option items Disable an individual option item by setting the `isDisabled` key to `true` within the object. ```jsx live-in-view () => { const [value, setValue] = React.useState(['alpine']); const onSubmit = () => { console.log('value', value); }; return ( <React.Fragment> <V2SelectInput isMulti label="Disable Option Items" value={value} onChange={setValue} isClearable isSearchable options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular', isDisabled: true }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> <V2Button onClick={onSubmit} css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </React.Fragment> ); }; ``` ### Option list height Use the `maxListHeight` prop to set the maximum height the option list can be before it becomes scrollable. The default value is `185px`. ```jsx live-in-view () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const [value1, setValue1] = React.useState([]); const [value2, setValue2] = React.useState([]); const [value3, setValue3] = React.useState([]); return ( <FormSpacing> <V2SelectInput isMulti label="100px max height" value={value1} onChange={setValue1} maxListHeight={100} options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> <V2SelectInput isMulti label="185px max height - Default" value={value2} onChange={setValue2} options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> <V2SelectInput isMulti label="250px max height" value={value3} onChange={setValue3} maxListHeight="250px" options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> </FormSpacing> ); }; ``` ### Section headers To group list items under section headers, pass objects into the `options` array that have the `section` and `items` properties. `section` specifies the name of the section, which will be bolded and unselectable, while `items` contains the options within that section (with the same `value`/`label` format as normal), which will appear indented. To retain section headers after searching with `isSearchable`, set `retainSectionHeader` within `searchConfig` to `true`. ```jsx [ { value: 'id1', label: 'Option 1' }, { value: 'id2', label: 'Option 2' }, { section: 'Section Header', items: [ { value: 'id3', label: 'Sub-section Option 1' }, { value: 'id4', label: 'Sub-section Option 2' }, ... ], }, ... ] ``` ```jsx live-in-view () => { const [value, setValue] = React.useState([]); return ( <V2SelectInput isMulti label="Section Headers Example" value={value} onChange={setValue} isSearchable searchConfig={{ retainSectionHeader: true }} options={[ { value: '1', label: 'This option is not under any section' }, { section: 'Section Header', items: [ { value: '11', label: 'Option 1' }, { value: '21', label: 'Option 2' }, ], }, { section: 'Other Section Header', items: [ { value: '31', label: 'Option 3' }, { value: '41', label: 'Option 4' }, ], }, , ]} /> ); }; ``` ### Custom render Use the `customRender` prop to customize the render of each option item. If [section headers](#section-headers) are used, they will also be handled by this function. `customRender` provides the item object as the first parameter and the item's state as the second. ```jsx live-in-view () => { const [value, setValue] = useState(); const customRender = (item, state) => { console.log('item', item); const defaultSettings = { icon: 'cancel', color: '$error1', variant: 'error', }; const getSettings = () => { const { status } = item; if (status === 'active') { return { icon: 'check_circle_outline', color: '$success1', variant: 'success', }; } return defaultSettings; }; const { icon, color, variant } = getSettings(); if (item.section) { return ( <Layout.Group> <span>{item.section}</span> <IconSymbol icon={icon} color={color} /> </Layout.Group> ); } return <Badge variant={variant}>{item.label}</Badge>; }; return ( <V2SelectInput isMulti label="Custom Render" value={value} onChange={setValue} isClearable isSearchable maxListHeight={300} options={[ { section: 'Active Options', status: 'active', items: [ { value: 'option_1', label: 'Option 1', status: 'active' }, { value: 'option_2', label: 'Option 2', status: 'active' }, { value: 'option_3', label: 'Option 3', status: 'active' }, ], }, { section: 'Inactive Options', status: 'inactive', items: [ { value: 'option_4', label: 'Option 4', status: 'inactive' }, { value: 'option_5', label: 'Option 5', status: 'inactive' }, { value: 'option_6', label: 'Option 6', status: 'inactive' }, ], }, ]} customRender={customRender} /> ); }; ``` ### Virtualization Use the `virtual` prop to add virtualization and improve performance when working with larger data sets. Virtualization leverages the `useVirtualization` hook, which utilizes the TanStack Virtual library. Setting `virtual` to `true` will utilize the default configuration. `virtual` also accepts an object to configure the virtualizer. To see all available values that may be provided to the `virtual` prop, please refer to the [TanStack Virtual documentation](https://tanstack.com/virtual/v3/docs/api/virtualizer). To maximize performance, virtualization for the V2SelectInput component is configured by default to use fixed sizing based on an option item element height of `38px`. If your item height remains fixed but is different from the default, utilize the [estimateSize](https://tanstack.com/virtual/latest/docs/api/virtualizer#estimatesize) function. If the item height is unknown prior to rendering, enable dynamic sizing by setting `dynamicSizing` to `true`. The default settings used in V2SelectInput are as follows: - `estimateSize`: Sets item height when using fixed sizing. When using dynamic sizing, to help with scroll performance, set this to the largest possible height of the item elements (default value is `38`). - `dynamicSizing`: When `true`, each option item element is dynamically measured on render. Scrolling performance may not be as smooth when using this prop (default value is `false`). - `overscan`: The number of element items to render above and below the visible area (default value is `5`). ```jsx live-in-view () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const defaultOptionCount = 5000; const withSectionHeaders = false; const optionNumberForm = useFormV2({ defaultValues: { optionCount: defaultOptionCount, }, }); const selectInputForm = useFormV2(); const [options, setOptions] = React.useState(); const generateOptions = (count) => { const options = Array.from(Array(Number(count)).keys()).map((i) => { const optionLabelValue = `Option ${i + 1}`; if (withSectionHeaders) { return { section: `Option ${i + 1} Header`, items: [ { label: `${optionLabelValue} A`, value: `${optionLabelValue}_A` }, { label: `${optionLabelValue} B`, value: `${optionLabelValue}_B` }, ], }; } return { label: optionLabelValue, value: optionLabelValue }; }); setOptions(options); }; useEffect(() => { generateOptions(defaultOptionCount); }, []); return ( <FormSpacing> <V2FormProvider state={optionNumberForm} onSubmit={({ optionCount }) => generateOptions(optionCount)} > <Layout.Group alignItems="bottom"> <V2TextInput label="Set Number of Dropdown Options" model="optionCount" mask="numeric" maskConfig={{ isAllowed: ({ floatValue }) => { const value = floatValue || 0; return value <= 100000; }, }} /> <V2Button type="submit">Update Options</V2Button> <V2Button variant="outline" type="button" onClick={() => { optionNumberForm.reset(); selectInputForm.reset(); generateOptions(defaultOptionCount); }} > Reset </V2Button> </Layout.Group> </V2FormProvider> <V2FormProvider state={selectInputForm}> <FormSpacing> <V2SelectInput isMulti selectAll label="SelectInput with Virtualization" model="selectWithVirtual" isClearable isSearchable options={options} virtual searchConfig={{ retainSectionHeader: withSectionHeaders }} /> <V2SelectInput isMulti selectAll label="SelectInput without Virtualization" model="selectWithoutVirtual" isClearable isSearchable options={options} searchConfig={{ retainSectionHeader: withSectionHeaders }} /> </FormSpacing> </V2FormProvider> </React.Fragment> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2SelectInput" propTypeName="SelectInputProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2ClassesTable title="V2SelectInput" classes={[SelectInputClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> A combobox is a widget made up of the combination of two distinct elements: - A single-line textbox. - An associated pop-up element for helping users set the value of the textbox. The popup may be a listbox, grid, tree, or dialog. Many implementations also include a third optional element -- a graphical button adjacent to the textbox, indicating the availability of the popup. Activating the button displays the popup if suggestions are available. V2SelectInput in multi-mode adheres to the <ExitLink href="https://www.w3.org/TR/wai-aria-practices-1.2/#combobox">Combobox WAI-ARIA design pattern</ExitLink>. However, V2SelectInput in multi-mode is not a standard combobox. - It is a merger of a list of selected chips (which can be cleared), and a combobox that allows selection. - We've moved the textbox into the pop-up menu above the listbox, and placed the chips where the textbox typically resides. - It is a multi-selection combobox - which lacks a specific WAI-ARIA example. - The most similar "single-select" combobox example (of the 5 provided) seems to be the <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-list/">Editable Combobox With List Autocomplete Example</ExitLink>. Thus, there is no fully defined WAI-ARIA pattern for SelectInputMulti. V2SelectInput in multi-mode follows the WAI-ARIA combobox standard for all keystrokes, except for the Enter key, which toggles the checkboxes in the list. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); const options = [ { label: 'Vanilla', value: '1' }, { label: 'Chocolate', value: '2' }, { label: 'Strawberry', value: '3' }, { label: 'Cookie Dough', value: '4' }, { label: 'Rocky Road', value: '5' }, ]; return ( <V2FormProvider state={form}> <FormSpacing> <V2SelectInput isMulti label="Ice cream flavors" subText="Must pick at least one" model="required" isSearchable options={options} validators={{ required: 'Pick at least one flavor' }} /> <V2SelectInput isMulti label="Ice cream flavors" model="custom-required" subText="Must pick at least one (with no search or custom messages)" options={options} validators={{ required: true }} /> <V2SelectInput isMulti label="Ice cream flavors" model="validate" subText="Must pick at least one, but no more than two flavors" isSearchable options={options} validators={{ required: 'Pick at least one flavor', validate: { noMoreThanTwoAllowed: (v) => { return v.length > 2 ? 'Select a maximum of two flavors' : true; }, }, }} /> </FormSpacing> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ```jsx render <Docs.AccessibilityTable title="Selection Box" rows={[ { name: 'Down Arrow', description: 'If the listbox is displayed: Moves focus to the second suggested value. Note that the first value is automatically selected. If the listbox is not displayed: opens the listbox and moves focus to the first value.', }, { name: 'Up Arrow', description: 'If the listbox is displayed, moves focus to the last suggested value. If the listbox is not displayed, opens the listbox and moves focus to the last value.', }, { name: 'Enter', description: 'If the listbox is displayed and the first option is automatically selected: Sets the textbox value to the content of the selected option. Closes the listbox.', }, { name: 'Esc', description: 'If the listbox is displayed, closes it.', }, { name: 'Supported Keystrokes', description: 'Supported keystrokes use character matching functionality to display matched values in the Listbox.', }, ]} /> ``` ```jsx render <Docs.AccessibilityTable title="Closed Selection Box" rows={[ { name: 'Enter', description: 'Opens the listbox and moves focus to the selected option in the listbox. If no option is selected it sets focus to the first option in the listbox', }, { name: 'Down Arrow', description: 'Opens the listbox and moves focus to the selected option in the listbox. If no option is selected it sets focus to the first option in the listbox', }, { name: 'Up Arrow', description: 'Opens the listbox and moves focus to the selected option in the listbox. If no option is selected it sets focus to the last option in the listbox', }, ]} /> ``` ```jsx render <Docs.AccessibilityTable title="Search Textbox" rows={[ { name: 'Down Arrow', description: 'Moves visual focus to the first value in the listbox', }, { name: 'Up Arrow', description: 'Moves visual focus to the last value in the listbox.', }, { name: 'Esc', description: 'Closes the menu.', }, { name: 'Home', description: 'Places the editing cursor at the beginning of the field.', }, { name: 'End', description: 'Places the editing cursor at the end of the field.', }, ]} /> ``` ```jsx render <Docs.AccessibilityTable title="Listbox (if isSearchable)" rows={[ { name: 'Enter', description: 'Toggles the currently highlighted checkbox. Closes the listbox. Sets focus on the selection container.', }, { name: 'Esc', description: 'Closes the listbox. Sets focus on the selection container.', }, { name: 'Down Arrow', description: 'Moves visual focus to the next option. If focus is on the last option, moves focus to the first option.', }, { name: 'Up Arrow', description: 'Moves visual focus to the previous option. If focus is on the first option, moves focus to the last option.', }, { name: 'Right Arrow', description: 'Moves focus to the textbox and moves the editing cursor one character to the right.', }, { name: 'Left Arrow', description: 'Moves focus to the textbox and moves the editing cursor one character to the left.', }, { name: 'Home', description: 'Moves focus to the textbox and places the editing cursor at the beginning of the field.', }, { name: 'End', description: 'Moves focus to the textbox and places the editing cursor at the end of the field.', }, ]} /> ``` ```jsx render <Docs.AccessibilityTable title="Listbox" rows={[ { name: 'Enter', description: 'Toggles the currently highlighted checkbox. Closes the listbox. Sets focus on the selection container.', }, { name: 'Esc', description: 'Closes the listbox. Sets focus on the selection container.', }, { name: 'Down Arrow', description: 'Moves focus to the next option.', }, { name: 'Up Arrow', description: 'Moves focus to the previous option.', }, { name: 'Home', description: 'Moves focus to the first option in the listbox.', }, { name: 'End', description: 'Moves focus to the last option in the listbox.', }, ]} /> ``` ```jsx render <Docs.AccessibilityTable title="Listbox" rows={[ { name: 'Enter', description: 'Toggles the currently highlighted checkbox.', }, { name: 'Esc', description: 'Closes the menu.', }, { name: 'Down Arrow', description: 'Moves visual focus to the next option.', }, { name: 'Up Arrow', description: 'Moves visual focus to the previous option.', }, { name: 'Home', description: 'Moves visual focus to the first option.', }, { name: 'End', description: 'Moves visual focus to the last option.', }, ]} /> ``` <h4>Known BrAT (Screen Reader) Issues</h4> - VoiceOver (MacOS) does not correctly announce combobox/listbox status - When expanded, combobox operation does not announce listbox selection or status - These issues match those in WAI-ARIA <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-none/">Editable Combobox without Autocomplete Example</ExitLink> - Un-searchable variant - Unlike searchable variant, NVDA does not announce "not selected" when options receive keyboard focus - JAWS correctly announced "not selected" for both variants </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={SelectInput} keys={['selectInputV2']} /> ``` </Tab> --- id: select-input-single-v2 category: Forms title: V2SelectInput (Single) description: Allows users to select one value from a provided list of options. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=10412-6930 sourcePath: ui/SelectInput/v2/V2SelectInput.tsx --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="SelectInput"></Docs.V2MigrationBanner> ``` ```jsx import { V2SelectInput } from '@uhg-abyss/web/ui/SelectInput'; ``` ```jsx sandbox { component: 'V2SelectInput', inputs: [ { prop: 'label', type: 'string', }, { prop: 'subText', type: 'string', }, { prop: 'width', type: 'string', }, { prop: 'hideLabel', type: 'boolean', }, { prop: 'isClearable', type: 'boolean', }, { prop: 'isDisabled', type: 'boolean', }, { prop: 'isSearchable', type: 'boolean', }, ], } () => { const [value, setValue] = React.useState('alpine'); const onSubmit = () => { console.log('value', value); }; return ( <React.Fragment> <V2SelectInput label="Your favorite framework/library" value={value} onChange={setValue} isClearable isSearchable options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> <V2Button onClick={onSubmit} css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }}> Submit </V2Button> </React.Fragment> ); }; ``` ## Usage ### Options Use the `options` prop to supply the drop-down menu options that will be available for selection. `options` is an array of objects, where each object has a base that includes the following properties: - `value`: unique identifier for the option - `label`: content the option will display within the menu list ```jsx [ { value: 'id1', label: 'Option 1' }, { value: 'id2', label: 'Option 2' }, { value: 'id3', label: 'Option 3' }, ... ] ``` Sections can also be specified. See [Section Headers](#section-headers) for more details. ### valueKey / labelKey If your data structure uses different property names than `value` and `label`, you can map them using the `valueKey` and `labelKey` props without restructuring your data. - `valueKey`: Specifies which property to use as the option's value (defaults to `"value"`) - `labelKey`: Specifies which property to use as the option's display text (defaults to `"label"`) This is particularly useful when working with API responses or existing data structures that can't be easily transformed. ```jsx live-in-view () => { const form = useFormV2(); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2SelectInput label="Label/Value Keys" model="keys" isClearable options={[ { name: 'Custom Option 1', id: 'a1' }, { name: 'Custom Option 2', id: 'b2' }, { name: 'Custom Option 3', id: 'c3' }, ]} labelKey="name" valueKey="id" /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ## Form integration ### useFormV2 (recommended) ```jsx render <Docs.FormMessage /> ``` <br /> ```jsx render <Docs.FormDisclaimer /> ``` ```jsx live-in-view () => { const form = useFormV2({ defaultValues: { selectForm: 'react', }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2SelectInput label="SelectInput useForm" model="selectForm" isClearable isSearchable onBlur={(e) => console.log('on blur form', e.target.value)} onFocus={(e) => console.log('on focus form', e.target.value)} options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} validators={{ required: true }} /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ### useState Using the `useState` hook gets values from the component state. ```jsx live-in-view () => { const [value, setValue] = React.useState('alpine'); const onSubmit = () => { console.log('value', value); }; const onChange = (newValue, selectedOption) => { console.log('onChange newValue:', newValue); console.log('onChange selectedOption', selectedOption); setValue(newValue); }; return ( <React.Fragment> <V2SelectInput label="SelectInput useState" value={value} onChange={onChange} onClear={() => setValue('')} onBlur={(e) => console.log('on blur state', e.target.value)} onFocus={(e) => console.log('on focus state', e.target.value)} isClearable isSearchable options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> <V2Button onClick={onSubmit} css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </React.Fragment> ); }; ``` ## Display properties ### Label The `label` prop is required. The `hideLabel` prop can be set to `true` to hide the label visually, but still allow it to be accessible to screen readers. ```jsx live-in-view () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <FormSpacing> <V2SelectInput label="Active Label" model="activeLabel" options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> <V2SelectInput label="Hidden Label" model="hiddenLabel" hideLabel css={{ 'abyss-select-input-root': { marginTop: '15px' } }} options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> </FormSpacing> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ### Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip-v2) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip-v2) or a [Popover](/web/ui/popover-v2). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip-v2/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live-in-view () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); const onSubmit = (data) => { console.log('data', data); }; const options = [ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <FormSpacing> <V2SelectInput label="Default Helper" helper="This is a tooltip" model="helper-tooltip" options={options} /> <V2SelectInput label="Custom Helper" helper={ <V2Popover title="Custom Helper" content="This is a popover with a custom icon" > <IconSymbol icon="help" variant="outlined" color="$success1" size="$md" /> </V2Popover> } model="helper-custom" options={options} validators={{ required: true }} /> </FormSpacing> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ### Subtext Use the `subText` prop to display helpful information related to the input field. The prop accepts either a string or an object of the form: ```ts { text: string; position: 'above' | 'below'; } ``` The `position` property determines where the subtext will be displayed in relation to the input field. The default value is `'below'`. ```jsx live-in-view () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2({ defaultValues: { subText: '1', }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <FormSpacing> <V2SelectInput label="SubText" subText={{ text: 'Subtext passed above the input', position: 'above', }} model="subText" validators={{ required: true }} options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> <V2SelectInput label="SubText" subText="Regular Subtext" model="subText2" validators={{ required: true }} options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> </FormSpacing> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ### Width Use the `width` prop to set the width of the select list. ```jsx live-in-view () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <FormSpacing> <V2SelectInput label="Default Width" model="widthDefault" isClearable options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> <V2SelectInput label="Width 75%" width="75%" model="width75" isClearable options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> <V2SelectInput label="Width 300px" width="300px" model="width300" isClearable options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> </FormSpacing> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ### Left element Use the `inputLeftElement` prop to add an element inside of the text input field. The recommended usage is for inserting icons. The prop accepts an object with the following properties: - `element`: The element to be displayed inside the input field. - `description`: An optional string that describes the purpose of the element for screen readers. These are considered decorative and do not need to be exposed to screen readers. That said, please note that icons should _not_ provide any information that is not also conveyed in a screen-readable way. For example, an exclamation mark (!) icon to indicate errors needs to be accompanied by `aria-invalid`. If the icon is used to convey additional information, use the `inputLeftElement.description` prop to provide a description for screen readers. ```jsx live () => { const form = useFormV2({}); return ( <V2FormProvider state={form}> <V2SelectInput label="Left Element" model="leftElement" isClearable inputLeftElement={{ element: ( <IconSymbol icon="language" size="$web.semantic.sizing.icon.utility.sm" color="$input-v2.color.icon.content" /> ), description: 'Language Icon', }} options={[ { label: 'English', value: '1' }, { label: 'Spanish', value: '2' }, { label: 'German', value: '3' }, ]} /> </V2FormProvider> ); }; ``` ## Validation ### Validators (useFormV2) ```jsx render <Docs.FormCompatibilityWidget useForm /> ``` Use the `validators` prop to set rules for the field to be valid. Note: The default error message when `required` is `true` is minimally acceptable for accessibility. It is highly recommended to customize it to be more specific to the use of the field and form. ```jsx live-in-view () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); const onSubmit = (data) => { console.log('data', data); }; const options = [ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, { label: 'Option 4', value: '4' }, { label: 'Option 5', value: '5' }, ]; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <FormSpacing> <V2SelectInput label="Required Default Message" model="required" isSearchable options={options} validators={{ required: true }} /> <V2SelectInput label="Required Custom Message" model="custom-required" isSearchable options={options} validators={{ required: 'Custom Error Message' }} /> <V2SelectInput label="Custom Validators" model="validate" isSearchable options={options} validators={{ required: true, validate: { greaterThanThree: (v) => { return v >= 3 || 'Should be "Option 3" or higher'; }, }, }} /> </FormSpacing> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ### Error message (useState) ```jsx render <Docs.FormCompatibilityWidget useState /> ``` Use the `errorMessage` prop to display a custom error message below the select field when using `useState`. ```jsx live-in-view () => { const [value, setValue] = useState(''); return ( <V2SelectInput label="Error Message" value={value} onChange={setValue} options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} errorMessage="Custom Error Message" /> ); }; ``` ### Success message ```jsx render <Docs.FormCompatibilityWidget useForm useState /> ``` Use the `successMessage` prop to display a custom success message below the input field. To provide a single success message across all form input components using `useFormV2`/`V2FormProvider`, you can provide `successMessage` to `V2FormProvider` as shown [here](/web/ui/form-provider-v2#successmessage). ```jsx live-in-view () => { const form = useFormV2(); const onSubmit = (data) => { // Do something on submit console.log(data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2SelectInput label="Success Message (useForm)" model="success-message" options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} successMessage="Selection is successful" validators={{ required: 'Selection is required', }} /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ```jsx live-in-view () => { const inputRef = useRef(null); const [value, setValue] = useState(''); const [isSubmitted, setIsSubmitted] = useState(false); const [errorMessage, setErrorMessage] = useState(''); const [successMessage, setSuccessMessage] = useState(''); const validate = () => { if (value === '') { setErrorMessage('Selection is required'); setSuccessMessage(''); inputRef.current.focus(); } else { setErrorMessage(''); setSuccessMessage('Selection is successful'); } }; const onSubmit = (e) => { e.preventDefault(); setIsSubmitted(true); validate(); }; useEffect(() => { if (isSubmitted) { validate(); } }, [value]); return ( <form onSubmit={onSubmit}> <V2SelectInput label="Success Message (useState)" value={value} onChange={setValue} isClearable ref={inputRef} options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} errorMessage={errorMessage} successMessage={successMessage} /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </form> ); }; ``` ### Highlighted ```jsx render <Docs.FormCompatibilityWidget useForm useState /> ``` Use the `highlighted` prop to enable the background color for the input. You can use `FormProvider` and `highlighted` to enable the color to appear if validation is required. ```jsx live-in-view () => { const [value, setValue] = useState(); return ( <V2SelectInput label="Your favorite framework/library" value={value} onChange={setValue} isClearable isSearchable highlighted options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> ); }; ``` ### Validation below menu ```jsx render <Docs.FormCompatibilityWidget useForm useState /> ``` Set the `validationBelowMenu` prop to `true` to relocate the error and success message validation to below the menu, when open. The default is `false` and the validation message will always remain displayed below the selection container, even when the menu is open. ```jsx live-in-view () => { const [value, setValue] = useState(); return ( <V2SelectInput label="Validation Below Menu" value={value} onChange={setValue} isClearable isSearchable errorMessage="Error Message" validationBelowMenu options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> ); }; ``` ## Interactivity ### Clearable Use the `isClearable` prop to allow for clearable select lists. If `true`, a clear button will appear in the input. The optional `onClear` callback prop can be used to trigger additional actions when the clear button is clicked. ```jsx live-in-view () => { const form = useFormV2({ defaultValues: { isClearableForm: '1', }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2SelectInput label="Clearable (with useForm)" model="isClearableForm" onClear={() => console.log('selection cleared')} isClearable options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> </V2FormProvider> ); }; ``` ```jsx live-in-view () => { const [value, setValue] = React.useState('1'); return ( <V2SelectInput label="Clearable (with useState)" value={value} onChange={setValue} isClearable options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> ); }; ``` ### Disabled Set the `isDisabled` prop to `true` to disable the select list input field, so users cannot select a value. ```jsx live-in-view () => { const form = useFormV2(); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2SelectInput label="Disabled" model="disabled" options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} isDisabled /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ### Enable outside scroll Set the `enableOutsideScroll` prop to `true` to enable scrolling outside the search input component while the option list is open. Default is set to `false`. ```jsx live-in-view () => { const [value, setValue] = React.useState('alpine'); const onSubmit = () => { console.log('value', value); }; return ( <React.Fragment> <V2SelectInput label="Your favorite framework/library" value={value} onChange={setValue} isClearable isSearchable enableOutsideScroll options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> <V2Button onClick={onSubmit} css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </React.Fragment> ); }; ``` ## Search filtering Use the `isSearchable` prop to add an input field within the drop-down menu for the user to search/filter the list of options. ```jsx live-in-view () => { const form = useFormV2(); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2SelectInput label="Searchable" model="searchable" isSearchable options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ### Fuse.js When applying `isSearchable`, it will fuzzy filter your results using the <ExitLink href="https://fusejs.io">Fuse.js</ExitLink> library. What is fuzzy searching?... Generally speaking, fuzzy searching (more formally known as approximate string matching) is the technique of finding strings that are approximately equal to a given pattern (rather than exactly). ```jsx live-in-view () => { const form = useFormV2(); return ( <V2FormProvider state={form}> <V2SelectInput model="search" label="Fuse Default Search" isClearable isSearchable options={[ { value: 'react', label: 'React', }, { value: 'ng', label: 'Angular', }, { value: 'svelte', label: 'Svelte', }, { value: 'preact', label: 'Preact', }, ]} /> </V2FormProvider> ); }; ``` ### Fuse keys The `keys` prop allows you to specify the values from the specific keys within your `options` object to search against. This feature accommodates nested paths, prioritizes certain fields with weighted search, and can handle searches within arrays of objects. The default search keys are `['label', 'value']`. For example, if the `options` contained objects of the following structure: ```ts { value: "react", label: "React", tags: ['jsx', 'virtual dom', 'facebook'] } ``` and you wanted to allow users to search on the label and tags values, you would provide the following, as in the example below: ```tsx searchConfig={{ keys: ['label', 'tags'] }} ``` ```jsx live-in-view () => { const form = useFormV2({}); return ( <V2FormProvider state={form}> <V2SelectInput label="Fuse Keys Search" searchConfig={{ keys: ['label', 'tags'] }} model="framework" isClearable isSearchable options={[ { value: 'react', label: 'React', tags: ['jsx', 'virtual dom', 'facebook'], }, { value: 'ng', label: 'Angular', tags: ['typescript', 'directives', 'google'], }, { value: 'svelte', label: 'Svelte', tags: ['compile-time', 'no virtual dom', 'rich harris'], }, ]} /> </V2FormProvider> ); }; ``` ### Custom Fuse configurations The Fuse configuration can be customized by following the <ExitLink href="https://fusejs.io/api/options.html">Fuse documentation</ExitLink> and passing the configurations into the `searchConfig` prop. For example, if you wanted to adjust the <ExitLink href="https://www.fusejs.io/api/options.html#threshold">threshold</ExitLink> to `0`, thus requiring an exact match, you would pass in the following object. The default threshold is `0.1`. ```tsx const customFuseConfig = { threshold: 0, // exact match }; ``` ```jsx live-in-view () => { const [sliderValue, setSliderValue] = useState(0); const form = useFormV2(); const customFuseConfig = { threshold: sliderValue, keys: ['label'], }; const marksConfig = { marks: [ { value: 0.0, label: 'Exact Match' }, { value: 0.2, label: '.2' }, { value: 0.4, label: '.4' }, { value: 0.6, label: '.6' }, { value: 0.8, label: '.8' }, { value: 1.0, label: 'Match Anything' }, ], }; return ( <V2FormProvider state={form}> <Layout.Stack grow> <V2SelectInput label="Custom Fuse Threshold Config" model="framework" isClearable highlighted isSearchable searchConfig={customFuseConfig} options={[ { value: 'react', label: 'React', }, { value: 'ng', label: 'Angular', }, { value: 'svelte', label: 'Svelte', }, { value: 'preact', label: 'Preact', }, ]} /> <V2Slider label="Search Threshold" subText="Adjust the slider to change the Fuse threshold value" marksConfig={marksConfig} minValue={0.0} maxValue={1.0} value={sliderValue} onChange={setSliderValue} step={0.2} /> </Layout.Stack> </V2FormProvider> ); }; ``` ### Highlighted search results By default, when searching, the matching text within all search results will be highlighted and the font weight will be updated based on the following criteria: - not selected: the matching text displays as bold - selected: the matching text displays as regular To override this behavior and turn off the highlighting, set the `highlightMatches` prop to `false`. ```jsx live-in-view () => { const [highlightMatches, setHighlightMatches] = useState(true); const form = useFormV2(); return ( <React.Fragment> <V2FormProvider state={form}> <V2SelectInput label="Highlighted Search Results" model="framework" isClearable isSearchable highlightMatches={highlightMatches} options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'preact', label: 'Preact' }, ]} /> </V2FormProvider> <V2Button onClick={() => setHighlightMatches(!highlightMatches)} css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > {highlightMatches ? 'Disable' : 'Enable'} Search Highlighting </V2Button> </React.Fragment> ); }; ``` ### API filtering with debounce To override the Fuse filtering and make asynchronous calls to an API to set the list of dropdown options, use a combination of the `onInputChange`, `options`, and `isLoading` props. While searching, `onInputChange` will supply the current search value and the value of the current selections. `isLoading` controls the built-in loading spinner. After retrieving the option items from the API, pass them into the `options` prop. To incorporate debouncing into the search, use the `useDebounce` hook. ```jsx import { useDebounce } from '@uhg-abyss/web/hooks/useDebounce'; ``` When using debounce, it is recommended to use the `customNoOptionsMessage` prop to control the display message when there are no options available and/or when no search results are found. This example shows all of these concepts together. The apiFilter function is called on every keystroke, but the API call is debounced to only occur after 600ms of inactivity. Search "united" to see the API call in action. ```jsx live-in-view () => { const noOptionsMessage = 'No options'; const [searchMessage, setSearchMessage] = useState(noOptionsMessage); const [results, setResults] = useState([]); const [loading, setLoading] = useState(false); const form = useFormV2(); const apiFilter = (searchValue, selectedValue) => { console.log('searchValue', searchValue); console.log('selectedValue', selectedValue); if (!searchValue) { setSearchMessage(noOptionsMessage); setResults([]); return; } setLoading(true); utils.useSearchInputMockApi(searchValue).then((response) => { setLoading(false); if (response.length === 0) { setSearchMessage(`No results found for ${searchValue}`); } console.log({ results, response }); setResults(response); }); }; const debouncedApiFilter = useDebounce(apiFilter, 600); // function, delay (ms) return ( <V2FormProvider state={form}> <V2SelectInput model="apiFiltering" label="API Filtering" isSearchable highlightMatches={false} customNoOptionsMessage={searchMessage} onInputChange={debouncedApiFilter} options={results} isLoading={loading} /> </V2FormProvider> ); }; ``` ## Menu option configurations ### Disable option items Disable an individual option item by setting the `isDisabled` key to `true` within the object. ```jsx live-in-view () => { const [value, setValue] = React.useState('alpine'); const onSubmit = () => { console.log('value', value); }; return ( <React.Fragment> <V2SelectInput label="Disable Option Items" value={value} onChange={setValue} isClearable isSearchable options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular', isDisabled: true }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> <V2Button onClick={onSubmit} css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </React.Fragment> ); }; ``` ### Option list height Use the `maxListHeight` prop to set the maximum height the option list can be before it becomes scrollable. The default value is `185px`. ```jsx live-in-view () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const [value1, setValue1] = React.useState(''); const [value2, setValue2] = React.useState(''); const [value3, setValue3] = React.useState(''); return ( <FormSpacing> <V2SelectInput label="100px max height" value={value1} onChange={setValue1} maxListHeight={100} options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> <V2SelectInput label="185px max height - Default" value={value2} onChange={setValue2} options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> <V2SelectInput label="250px max height" value={value3} onChange={setValue3} maxListHeight="250px" options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> </FormSpacing> ); }; ``` ### Section headers To group list items under section headers, pass objects into the `options` array that have the `section` and `items` properties. `section` specifies the name of the section, which will be bolded and unselectable, while `items` contains the options within that section (with the same `value`/`label` format as normal), which will appear indented. To retain section headers after searching with `isSearchable`, set `retainSectionHeader` within `searchConfig` to `true`. ```jsx [ { value: 'id1', label: 'Option 1' }, { value: 'id2', label: 'Option 2' }, { section: 'Section Header', items: [ { value: 'id3', label: 'Sub-section Option 1' }, { value: 'id4', label: 'Sub-section Option 2' }, ... ], }, ... ] ``` ```jsx live-in-view () => { const [value, setValue] = React.useState(''); return ( <V2SelectInput label="Section Headers Example" value={value} onChange={setValue} isSearchable searchConfig={{ retainSectionHeader: true }} options={[ { value: '1', label: 'This option is not under any section' }, { section: 'Section Header', items: [ { value: '11', label: 'Option 1' }, { value: '21', label: 'Option 2' }, ], }, { section: 'Other Section Header', items: [ { value: '31', label: 'Option 3' }, { value: '41', label: 'Option 4' }, ], }, , ]} /> ); }; ``` ### Custom render Use the `customRender` prop to customize the render of each option item. If [section headers](#section-headers) are used, they will also be handled by this function. `customRender` provides the item object as the first parameter and the item's state as the second. ```jsx live-in-view () => { const [value, setValue] = useState(); const customRender = (item, state) => { console.log('item', item); const defaultSettings = { icon: 'cancel', color: '$error1', variant: 'error', }; const getSettings = () => { const { status } = item; if (status === 'active') { return { icon: 'check_circle_outline', color: '$success1', variant: 'success', }; } return defaultSettings; }; const { icon, color, variant } = getSettings(); if (item.section) { return ( <Layout.Group> <span>{item.section}</span> <IconSymbol icon={icon} color={color} /> </Layout.Group> ); } return <Badge variant={variant}>{item.label}</Badge>; }; return ( <V2SelectInput label="Custom Render" value={value} onChange={setValue} isClearable isSearchable maxListHeight={300} options={[ { section: 'Active Options', status: 'active', items: [ { value: 'option_1', label: 'Option 1', status: 'active' }, { value: 'option_2', label: 'Option 2', status: 'active' }, { value: 'option_3', label: 'Option 3', status: 'active' }, ], }, { section: 'Inactive Options', status: 'inactive', items: [ { value: 'option_4', label: 'Option 4', status: 'inactive' }, { value: 'option_5', label: 'Option 5', status: 'inactive' }, { value: 'option_6', label: 'Option 6', status: 'inactive' }, ], }, ]} customRender={customRender} /> ); }; ``` ### Virtualization Use the `virtual` prop to add virtualization and improve performance when working with larger data sets. Virtualization leverages the `useVirtualization` hook, which utilizes the TanStack Virtual library. Setting `virtual` to `true` will utilize the default configuration. `virtual` also accepts an object to configure the virtualizer. To see all available values that may be provided to the `virtual` prop, please refer to the [TanStack Virtual documentation](https://tanstack.com/virtual/v3/docs/api/virtualizer). To maximize performance, virtualization for the V2SelectInput component is configured by default to use fixed sizing based on an option item element height of `38px`. If your item height remains fixed but is different from the default, utilize the [estimateSize](https://tanstack.com/virtual/latest/docs/api/virtualizer#estimatesize) function. If the item height is unknown prior to rendering, enable dynamic sizing by setting `dynamicSizing` to `true`. The default settings used in V2SelectInput are as follows: - `estimateSize`: Sets item height when using fixed sizing. When using dynamic sizing, to help with scroll performance, set this to the largest possible height of the item elements (default value is `38`). - `dynamicSizing`: When `true`, each option item element is dynamically measured on render. Scrolling performance may not be as smooth when using this prop (default value is `false`). - `overscan`: The number of element items to render above and below the visible area (default value is `5`). ```jsx live-in-view () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const defaultOptionCount = 5000; const withSectionHeaders = false; const optionNumberForm = useFormV2({ defaultValues: { optionCount: defaultOptionCount, }, }); const selectInputForm = useFormV2(); const [options, setOptions] = React.useState(); const generateOptions = (count) => { const options = Array.from(Array(Number(count)).keys()).map((i) => { const optionLabelValue = `Option ${i + 1}`; if (withSectionHeaders) { return { section: `Option ${i + 1} Header`, items: [ { label: `${optionLabelValue} A`, value: `${optionLabelValue}_A` }, { label: `${optionLabelValue} B`, value: `${optionLabelValue}_B` }, ], }; } return { label: optionLabelValue, value: optionLabelValue }; }); setOptions(options); }; useEffect(() => { generateOptions(defaultOptionCount); }, []); return ( <FormSpacing> <V2FormProvider state={optionNumberForm} onSubmit={({ optionCount }) => generateOptions(optionCount)} > <Layout.Group alignItems="bottom"> <V2TextInput label="Set Number of Dropdown Options" model="optionCount" mask="numeric" maskConfig={{ isAllowed: ({ floatValue }) => { const value = floatValue || 0; return value <= 100000; }, }} /> <V2Button type="submit">Update Options</V2Button> <V2Button variant="outline" type="button" onClick={() => { optionNumberForm.reset(); selectInputForm.reset(); generateOptions(defaultOptionCount); }} > Reset </V2Button> </Layout.Group> </V2FormProvider> <V2FormProvider state={selectInputForm}> <FormSpacing> <V2SelectInput label="SelectInput with Virtualization" model="selectWithVirtual" isClearable isSearchable options={options} virtual searchConfig={{ retainSectionHeader: withSectionHeaders }} /> <V2SelectInput label="SelectInput without Virtualization" model="selectWithoutVirtual" isClearable isSearchable options={options} searchConfig={{ retainSectionHeader: withSectionHeaders }} /> </FormSpacing> </V2FormProvider> </React.Fragment> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2SelectInput" propTypeName="SelectInputProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2ClassesTable title="V2SelectInput" classes={[SelectInputClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> A combobox is a widget made up of the combination of two distinct elements: 1) a single-line textbox, and 2) an associated pop-up element for helping users set the value of the textbox. The popup may be a listbox, grid, tree, or dialog. Many implementations also include a third optional element -- a graphical button adjacent to the textbox, indicating the availability of the popup. Activating the button displays the popup if suggestions are available. Adheres to the <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/combobox/">Combo box WAI-ARIA design pattern</ExitLink>. Listed Below are example use cases: - <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-select-only/"> Select-Only Combobox Example </ExitLink> - <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-list/"> Editable Combobox With List Autocomplete Example </ExitLink> - <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/listbox/examples/listbox-grouped/"> Listbox Example with Grouped Options </ExitLink> ```jsx live-in-view () => { const form = useFormV2({ defaultValues: { framework: 'react', }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form}> <V2SelectInput label="Pick free menu option" model="subText2" subText="Taxes may apply to additional items" isClearable isSearchable options={[ { value: '1', label: 'Nothing' }, { section: 'Drinks', items: [ { value: '10', label: 'Water' }, { value: '20', label: 'Soft drinks' }, { value: '30', label: 'Beer', isDisabled: true }, ], }, { section: 'Entrees', items: [ { value: '11', label: 'Hamburger' }, { value: '21', label: 'Chicken Tenders' }, ], }, { section: 'Sides', items: [ { value: '31', label: 'French Fries' }, { value: '41', label: 'Onion Rings' }, ], }, ]} validators={{ required: true }} /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ```jsx render <Docs.AccessibilityTable title="Selection Box" rows={[ { name: 'Down Arrow', description: 'If the listbox is displayed: Moves focus to the second suggested value. Note that the first value is automatically selected. If the listbox is not displayed: opens the listbox and moves focus to the first value.', }, { name: 'Up Arrow', description: 'If the listbox is displayed, moves focus to the last suggested value. If the listbox is not displayed, opens the listbox and moves focus to the last value.', }, { name: 'Enter', description: 'If the listbox is displayed and the first option is automatically selected: Sets the textbox value to the content of the selected option. Closes the listbox.', }, { name: 'Esc', description: 'If the listbox is displayed, closes it.', }, { name: 'Supported Keystrokes', description: 'Supported keystrokes use character matching functionality to display matched values in the Listbox.', }, ]} /> ``` ```jsx render <Docs.AccessibilityTable title="Closed Selection Box" rows={[ { name: 'Enter', description: 'Opens the listbox and moves focus to the selected option in the listbox. If no option is selected it sets focus to the first option in the listbox', }, { name: 'Down Arrow', description: 'Opens the listbox and moves focus to the selected option in the listbox. If no option is selected it sets focus to the first option in the listbox', }, { name: 'Up Arrow', description: 'Opens the listbox and moves focus to the selected option in the listbox. If no option is selected it sets focus to the last option in the listbox', }, ]} /> ``` ```jsx render <Docs.AccessibilityTable title="Closed Selection Box (isSearchable)" rows={[ { name: 'Enter', description: 'Opens the listbox and moves focus to the search text box.', }, { name: 'Down Arrow', description: 'Opens the listbox and moves focus to the search text box.', }, { name: 'Up Arrow', description: 'Opens the listbox and moves focus to the search text box.', }, ]} /> ``` ```jsx render <Docs.AccessibilityTable title="Search Textbox" rows={[ { name: 'Down Arrow', description: 'Moves visual focus to the first value in the listbox', }, { name: 'Up Arrow', description: 'Moves visual focus to the last value in the listbox.', }, { name: 'Esc', description: 'Closes the menu.', }, { name: 'Home', description: 'Places the editing cursor at the beginning of the field.', }, { name: 'End', description: 'Places the editing cursor at the end of the field.', }, ]} /> ``` ```jsx render <Docs.AccessibilityTable title="Listbox (if isSearchable)" rows={[ { name: 'Enter', description: 'Sets the selection value to the content of the focused option in the listbox. Closes the listbox. Sets focus on the selection box.', }, { name: 'Esc', description: 'Closes the listbox. Sets focus on the selection box.', }, { name: 'Down Arrow', description: 'Moves focus to the next option. If focus is on the last option, moves focus to the first option.', }, { name: 'Up Arrow', description: 'Moves focus to the previous option. If focus is on the first option, moves focus to the last option.', }, { name: 'Right Arrow', description: 'Moves focus to the textbox and moves the editing cursor one character to the right.', }, { name: 'Left Arrow', description: 'Moves focus to the textbox and moves the editing cursor one character to the left.', }, { name: 'Home', description: 'Moves focus to the textbox and places the editing cursor at the beginning of the field.', }, { name: 'End', description: 'Moves focus to the textbox and places the editing cursor at the end of the field.', }, ]} /> ``` ```jsx render <Docs.AccessibilityTable title="Listbox" rows={[ { name: 'Enter', description: 'Sets the selection value to the content of the focused option in the listbox. Closes the listbox. Sets focus on the selection container.', }, { name: 'Esc', description: 'Closes the listbox. Sets focus on the selection container.', }, { name: 'Down Arrow', description: 'Moves focus to the next option.', }, { name: 'Up Arrow', description: 'Moves focus to the previous option.', }, { name: 'Home', description: 'Moves focus to the first option in the listbox.', }, { name: 'End', description: 'Moves focus to the last option in the listbox.', }, ]} /> ``` <h2> BrAT Bugs </h2> - Issues below reproduced in WAI-ARIA <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-list/">Editable Combobox With List Autocomplete Example</ExitLink> - MacOS/Safari does not announce anything related to listbox (expanded, collapsed, options) - This makes the result count somewhat more helpful - NVDA does not announce aria-selected even when applied - JAWS announces each entries as selected which is correct based upon the standard <h2> Notes </h2> - Hiding the label negatively impacts accessibility. - Labels are required for fields - Hiding labels requires sited users to guess their name - This can increase the difficulty of speech recognition when speaking the command to "click" the field - Supplemental information is supplied from the downshift library </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={SelectInput} keys={['selectInputV2']} /> ``` </Tab> --- id: select-input category: Forms title: SelectInput description: Allows users to select one value from a provided list of options. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=0-1195 --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="SelectInput"></Docs.V2MigrationBanner> ``` ```jsx import { SelectInput } from '@uhg-abyss/web/ui/SelectInput'; ``` ```jsx sandbox { component: 'SelectInput', inputs: [ { prop: 'label', type: 'string', defaultValue: 'Sandbox', }, { prop: 'placeholder', type: 'string', }, { prop: 'subText', type: 'string', }, { prop: 'width', type: 'string', }, { prop: 'hideLabel', type: 'boolean', }, { prop: 'isClearable', type: 'boolean', }, { prop: 'isDisabled', type: 'boolean', }, { prop: 'isSearchable', type: 'boolean', }, { prop: 'highlighted', type: 'boolean', defaultValue: false, }, ], } () => { const [value, setValue] = React.useState('alpine'); const onSubmit = () => { console.log('value', value); }; return ( <React.Fragment> <SelectInput label="Your favorite framework/library" placeholder="Pick one" value={value} onChange={setValue} onClear={() => setValue('')} isClearable isSearchable options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> <Button onClick={onSubmit} style={{ marginTop: '15px' }}> Submit </Button> </React.Fragment> ); }; ``` ## Usage Use the `options` prop to supply the options that can be selected. `options` is an array of objects, where each object should have two properties: - `value`, which is a unique identifier for the option - `label`, which is how the option will be displayed in the list Sections can also be specified, in which case the section object should have `section` and `items` properties instead of `label` and `value` (See [Section Headers](#section-headers) for more details). ## useForm (recommended) Using the `useForm` hook lets the DOM handle form data. ```jsx live () => { const form = useForm({ defaultValues: { framework: 'react', }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <SelectInput label="Your favorite framework/library" placeholder="Pick one" model="framework" isClearable isSearchable options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} validators={{ required: true }} /> <Button type="submit" style={{ marginTop: '15px' }}> Submit </Button> </FormProvider> ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [value, setValue] = React.useState('alpine'); const onSubmit = () => { console.log('value', value); }; const onChange = (newValue, selectedOption) => { console.log('onChange newValue:', newValue); console.log('onChange selectedOption', selectedOption); setValue(newValue); }; return ( <React.Fragment> <SelectInput label="Your favorite framework/library" placeholder="Pick one" value={value} onChange={onChange} onClear={() => setValue('')} isClearable isSearchable options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> <Button onClick={onSubmit} style={{ marginTop: '15px' }}> Submit </Button> </React.Fragment> ); }; ``` ## Section headers To create section headers in the list, pass objects into the `options` array that have the `section` and `items` properties. `section` specifies the name of the section, which will be bolded and un-selectable, while `items` should contain the options within that section (with the same `value`/`label` format as normal), which will appear indented. The `retainSectionHeader` prop can be passed in to retain the corresponding section headers in the results when searching. ```jsx [ { value: 'id1', label: 'Option 1' }, { value: 'id2', label: 'Option 2' }, { section: 'Section Header', items: [ { value: 'id3', label: 'Sub-section Option 1' }, { value: 'id4', label: 'Sub-section Option 2' }, ... ], }, ... ] ``` ```jsx live () => { const [value, setValue] = React.useState(''); return ( <SelectInput label="Section Headers Example" placeholder="Pick one" value={value} onChange={setValue} onClear={() => setValue('')} isSearchable retainSectionHeader options={[ { value: '1', label: 'This option is not under any section' }, { section: 'Section Header', items: [ { value: '11', label: 'Option 1' }, { value: '21', label: 'Option 2' }, ], }, { section: 'Other Section Header', items: [ { value: '31', label: 'Option 3' }, { value: '41', label: 'Option 4' }, ], }, , ]} /> ); }; ``` ## Add elements inside input Use the `inputLeftElement` and `inputRightElement` props to add elements to the inside of the select input field. The recommended usage is for inserting icons. These are considered decorative and do not need to be exposed to screen readers. That said, please note that icons should _not_ provide any information that is not also conveyed in a screen-readable way. For example, an (!) icon to indicate errors needs to be accompanied by `aria-invalid`. If icons are used to convey additional information, use the `inputLeftElementDescription` and `inputRightElementDescription` props to provide a description for screen readers. See the [Validation](#validation) section below for an example on how to incorporate with validation and display error/success states with icons. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <SelectInput label="Add Elements" placeholder="select option" inputLeftElement={<IconSymbol icon="star" size="20px" color="$gray6" />} inputRightElement={<IconSymbol icon="check" size="20px" />} inputLeftElementDescription="Star Icon" inputRightElementDescription="Checkmark Icon" model="activeLabel" isClearable isSearchable options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> </FormProvider> ); }; ``` ## Label The `label` prop is required. To hide the label use the `hideLabel` prop to show or hide the label. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <SelectInput label="Active Label" placeholder="Active Label" model="activeLabel" options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> <SelectInput label="Hidden Label" placeholder="Hidden Label" model="hiddenLabel" hideLabel css={{ 'abyss-select-input-root': { marginTop: '15px' } }} options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> <Button type="submit" css={{ marginTop: '15px' }}> Submit </Button> </FormProvider> ); }; ``` ## Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip) or a [Popover](/web/ui/popover). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; const options = [ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]; return ( <FormProvider state={form}> <SelectInput label="Default Helper" helper="This is a tooltip" model="helper-tooltip" options={options} /> <SelectInput label="Custom Helper" helper={ <Popover title="Custom Helper" content="This is a popover with a custom icon" > <IconSymbol icon="help" variant="outlined" color="$success1" size="$sm" /> </Popover> } model="helper-custom" options={options} validators={{ required: true }} /> <Button type="submit" css={{ marginTop: '15px' }}> Submit </Button> </FormProvider> ); }; ``` ## Disabled Set the `isDisabled` prop to `true` to disable the select list input field so users cannot select a value. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <SelectInput label="Disabled" isDisabled={true} model="disabled" options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> <Button type="submit" style={{ marginTop: '15px' }}> Submit </Button> </FormProvider> ); }; ``` ## Disable option items Disable an individual option item by setting the `isDisabled` key to `true` within the object. ```jsx live () => { const [value, setValue] = React.useState('alpine'); const onSubmit = () => { console.log('value', value); }; return ( <React.Fragment> <SelectInput label="Disable Option Items" placeholder="Pick one" value={value} onChange={setValue} onClear={() => setValue('')} isClearable isSearchable options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular', isDisabled: true }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> <Button onClick={onSubmit} style={{ marginTop: '15px' }}> Submit </Button> </React.Fragment> ); }; ``` ## SubText Use the `subText` prop to display helpful text below the select list input field. ```jsx live () => { const form = useForm({ defaultValues: { subText: '1', }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <SelectInput label="SubText" subText="SubText Example" model="subText" validators={{ required: true }} options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> <Button type="submit" style={{ marginTop: '15px' }}> Submit </Button> </FormProvider> ); }; ``` ## Descriptors display Use the `descriptorsDisplay` prop to set the orientation of the error message and subtext descriptor content. Available variants include 'column' and 'row'. The default is set to 'row'. Use the [FormProvider](/web/ui/form-provider#descriptors-display) and `descriptorsDisplay` to set the descriptors orientation across an entire form. Note: The errorMessage prop does not work with useForm and is only applicable within our form input components when useState is being utilized. See the [useForm Docs](/web/hooks/use-form#set-error) for example use cases with useForm. ```jsx live () => { const [value, setValue] = React.useState(); return ( <SelectInput value={value} onChange={setValue} options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} placeholder="Pick one" label="Descriptors Display" subText="Subtext Message" errorMessage="Error Message" descriptorsDisplay="column" /> ); }; ``` ## Loading Use the `isLoading` prop to to display a loading spinner in place of the drop-down option list. This is useful when loading in the SelectInput options. ```jsx live () => { const [isLoading, setIsLoading] = useState(true); const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( <Layout.Stack grow> <FormProvider state={form} onSubmit={onSubmit}> <SelectInput label="Loading" placeholder={isLoading ? 'Loading...' : 'Select One'} isLoading={isLoading} model="loading" isClearable options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> </FormProvider> <Button onClick={() => setIsLoading(!isLoading)} style={{ marginTop: '15px' }} > Toggle Loading </Button> </Layout.Stack> ); }; ``` ## Searchable Use the `isSearchable` prop to display an input field for the user to search/filter the list of options. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <SelectInput label="Searchable" model="searchable" isSearchable options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> <Button type="submit" style={{ marginTop: '15px' }}> Submit </Button> </FormProvider> ); }; ``` ### Fuse.js When applying `isSearchable` to SelectInput, it will fuzzy filter your results using the <ExitLink href="https://fusejs.io">Fuse.js</ExitLink> library. What is fuzzy searching?... Generally speaking, fuzzy searching (more formally known as approximate string matching) is the technique of finding strings that are approximately equal to a given pattern (rather than exactly). ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <SelectInput placeholder="Search..." model="search" label="Fuse Default Search" isClearable isSearchable options={[ { value: 'react', label: 'React', }, { value: 'ng', label: 'Angular', }, { value: 'svelte', label: 'Svelte', }, { value: 'preact', label: 'Preact', }, ]} /> </FormProvider> ); }; ``` ### Fuse keys The `keys` prop allows you to specify the values from the specific keys within your `options` object to search against. This feature accommodates nested paths, prioritizes certain fields with weighted search, and can handle searches within arrays of objects. The default search keys are `['label', 'value']`. For example, if you wanted to search on the `label` and `tags` values in your object, you would pass in `keys={['label', 'tags']}`. ```javascript { value: "react", label: "React", tags: ['jsx', 'virtual dom', 'facebook'] } ``` ```jsx live () => { const form = useForm({}); return ( <FormProvider state={form}> <SelectInput label="Fuse Keys Search" placeholder="Pick one" keys={['label', 'tags']} model="framework" isClearable isSearchable options={[ { value: 'react', label: 'React', tags: ['jsx', 'virtual dom', 'facebook'], }, { value: 'ng', label: 'Angular', tags: ['typescript', 'directives', 'google'], }, { value: 'svelte', label: 'Svelte', tags: ['compile-time', 'no virtual dom', 'rich harris'], }, ]} /> </FormProvider> ); }; ``` ### Custom Fuse configurations You can customize the fuse filter by following the documentation on <ExitLink href="https://fusejs.io/api/options.html">Fuse</ExitLink> and passing your configurations into the `fuseConfig` prop. For example, if you wanted to adjust the <ExitLink href="https://www.fusejs.io/api/options.html#threshold">threshold</ExitLink> to `0` so the search criteria requires an exact match, you would pass in the following object. The default threshold is `0.1`. ```jsx const customFuseConfig = { threshold: 0, // exact match }; ``` ```jsx live () => { const [sliderValue, setSliderValue] = useState(0); const form = useForm(); const customFuseConfig = { threshold: sliderValue / 100, }; return ( <FormProvider state={form}> <SelectInput label="Custom Fuse Threshold Config" placeholder="Pick one" keys={['label']} model="framework" isClearable isSearchable fuseConfig={customFuseConfig} options={[ { value: 'react', label: 'React', }, { value: 'ng', label: 'Angular', }, { value: 'svelte', label: 'Svelte', }, { value: 'preact', label: 'Preact', }, ]} /> <Slider css={{ 'abyss-slider-label': { marginTop: '20px', }, '&.abyss-slider-root': { width: '85%', marginLeft: 'auto', marginRight: 'auto', }, }} label="Search Threshold" value={sliderValue} onChange={setSliderValue} step={20} showMarks marks={[ { value: 0, label: 'Exact Match' }, { value: 20, label: '.2' }, { value: 40, label: '.4' }, { value: 60, label: '.6' }, { value: 80, label: '.8' }, { value: 100, label: 'Match Anything' }, ]} /> </FormProvider> ); }; ``` ## onInputChange The `onInputChange` prop is an event handler called when the value of the text input changes while searching. The callback returns the current search value of the input. Use the `onChange` event handler to capture the value of an option item on selection. ```jsx live () => { const form = useForm(); const onInputChange = (value) => { console.log('value', value); }; return ( <FormProvider state={form}> <SelectInput label="onInputChange" hideLabel placeholder="Search..." model="onInputChange" isClearable isSearchable options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} onInputChange={onInputChange} /> </FormProvider> ); }; ``` ## API filtering with debounce Use the `apiFiltering` prop to override the fuse.js filtering and supply a custom function to make asynchronous calls to an API. Both current value and selected value results will be passed to the apiFiltering callback. The results from your API should be passed into the `options` prop. If `debounceTime` is not passed, a default debounce time of 1000ms will be applied. In the example below, search by the string `united` to see results. ```jsx live () => { const [results, setResults] = useState([]); const [loading, setLoading] = useState(false); const form = useForm(); const handleSearch = (data) => { console.log('Searched', data); }; const apiFilter = (currentValue, selectedValue) => { console.log('currentValue', currentValue); console.log('selectedValue', selectedValue); setLoading(true); utils.useSearchInputMockApi(currentValue).then((response) => { setLoading(false); setResults(response); }); }; return ( <FormProvider state={form}> <SelectInput placeholder="Search..." model="apiFiltering" label="Api Filtering" isSearchable options={results} isLoading={loading} debounceTime={1200} apiFiltering={apiFilter} /> </FormProvider> ); }; ``` ## Custom render Use the `customRender` prop to customize the render of each option item. If [Section Headers](#section-headers) are used they will also be handled by this function. `customRender` provides the item object as the first parameter and the items state as the second. ```jsx live () => { const [value, setValue] = useState(); const customRender = (item, state) => { const defaultSettings = { icon: 'cancel', color: '$error1', variant: 'error', }; const getSettings = () => { const { status } = (item.items && item.items[0]) || item; if (status === 'active') { return { icon: 'check_circle_outline', color: '$success1', variant: 'success', }; } return defaultSettings; }; const { icon, color, variant } = getSettings(); if (!!item.section) { return ( <Layout.Group> <span>{item.section}</span> <IconSymbol icon={icon} color={color} /> </Layout.Group> ); } return <Badge variant={variant}>{item.label}</Badge>; }; return ( <SelectInput label="Custom Render" placeholder="Pick one" value={value} onChange={setValue} onClear={() => setValue('')} isClearable isSearchable maxListHeight={300} options={[ { section: 'Active Options', items: [ { value: 'option_1', label: 'Option 1', status: 'active' }, { value: 'option_2', label: 'Option 2', status: 'active' }, { value: 'option_3', label: 'Option 3', status: 'active' }, ], }, { section: 'Inactive Options', items: [ { value: 'option_4', label: 'Option 4', status: 'inactive' }, { value: 'option_5', label: 'Option 5', status: 'inactive' }, { value: 'option_6', label: 'Option 6', status: 'inactive' }, ], }, ]} customRender={customRender} /> ); }; ``` ## Width Use the `width` prop to set the width of the select list. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <SelectInput label="Default Width" placeholder="Width: Default" model="widthDefault" isClearable options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> <SelectInput label="Width 75%" width="75%" placeholder="Width: 75%" model="width75" isClearable options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> <SelectInput label="Width" placeholder="Width: 300px" width="300px" model="width300" isClearable options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> <Button type="submit" style={{ marginTop: '15px' }}> Submit </Button> </FormProvider> ); }; ``` ## Option list height Use the `maxListHeight` prop to set the maximum height the option list can be before it becomes scrollable. The default value is `185px`. ```jsx live () => { const [value1, setValue1] = React.useState(''); const [value2, setValue2] = React.useState(''); const [value3, setValue3] = React.useState(''); return ( <React.Fragment> <SelectInput label="100px max height" placeholder="Pick one" value={value1} onChange={setValue1} maxListHeight={100} options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> <SelectInput label="185px max height - Default" placeholder="Pick one" value={value2} onChange={setValue2} options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> <SelectInput label="250px max height" placeholder="Pick one" value={value3} onChange={setValue3} maxListHeight="250px" options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> </React.Fragment> ); }; ``` ## Clearable Use the `isClearable` prop to to allow for clearable select lists. If `true`, a clear button will appear in the input. Note that if you are using `useState`, you will need to pass the `onClear` prop as well to handle clearing the data when the clear button is pressed. ```jsx live () => { const form = useForm({ defaultValues: { isClearableForm: '1', }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <SelectInput label="Clearable (with useForm)" placeholder="Pick one" model="isClearableForm" isClearable options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> </FormProvider> ); }; ``` ```jsx live () => { const [value, setValue] = React.useState('1'); return ( <SelectInput label="Clearable (with useState)" placeholder="Pick one" value={value} onChange={setValue} onClear={() => setValue('')} isClearable options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> ); }; ``` ## Label/value key Use the `valueKey` and `labelKey` props to change the key thats used to read the labels and values from the options list. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <SelectInput label="Label/Value Keys" placeholder="Label/Value Keys" model="keys" isClearable labelKey="label" valueKey="value" options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> </FormProvider> ); }; ``` ## Validation Use the validators prop to set rules for the field to be valid. ```jsx live () => { const form = useForm(); const { errors, isSubmitted, isSubmitSuccessful } = form.formState; const getIconProps = useCallback( (model) => { if (!isSubmitted) return {}; let iconProps = {}; if (!!errors[model]) { iconProps = { icon: 'error', color: '$error1', size: '18px' }; } if (isSubmitSuccessful) { iconProps = { icon: 'check', color: '$success1', size: '18px' }; } const isEmpty = Object.keys(iconProps).length === 0; return !isEmpty ? { inputRightElement: <IconSymbol {...iconProps} /> } : {}; }, [isSubmitted, isSubmitSuccessful] ); const options = [ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, { label: 'Option 4', value: '4' }, { label: 'Option 5', value: '5' }, ]; return ( <FormProvider state={form}> <SelectInput label="Required Default Message" model="required" isSearchable options={options} {...getIconProps('required')} validators={{ required: true }} /> <SelectInput label="Required Custom Message" model="custom-required" isSearchable options={options} validators={{ required: 'Custom Error Message' }} /> <SelectInput label="Custom Validators" model="validate" isSearchable options={options} validators={{ required: true, validate: { greaterThanThree: (v) => { return v >= 3 || 'Should be "Option 3" or higher'; }, }, }} /> <Button type="submit" style={{ marginTop: 15 }}> Submit </Button> </FormProvider> ); }; ``` ## Highlighted Use the `highlighted` prop to enable the background color for the input. You can use `FormProvider` and `highlighted` to enable the color to appear if validation is required. ```jsx live () => { const [value, setValue] = useState(); return ( <SelectInput label="Your favorite framework/library" placeholder="Pick one" value={value} onChange={setValue} onClear={() => setValue('')} isClearable isSearchable highlighted options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> ); }; ``` ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit} highlighted> <SelectInput label="Your favorite framework/library" placeholder="Pick one" model="framework" isClearable isSearchable options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} validators={{ required: true }} /> <Button type="submit" style={{ marginTop: 15 }}> Submit </Button> </FormProvider> ); }; ``` ## Enable outside scroll Set the `enableOutsideScroll` prop to `true` to enable scroll outside of the search input component while the option list is open. Default is set to `false`. ```jsx live () => { const [value, setValue] = React.useState('alpine'); const onSubmit = () => { console.log('value', value); }; return ( <React.Fragment> <SelectInput label="Your favorite framework/library" placeholder="Pick one" value={value} onChange={setValue} onClear={() => setValue('')} isClearable isSearchable enableOutsideScroll options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> <Button onClick={onSubmit} style={{ marginTop: '15px' }}> Submit </Button> </React.Fragment> ); }; ``` ## Virtualization Use the `virtual` prop to add virtualization and improve performance when working with larger data sets. Virtualization leverages the `useVirtualization` hook which utilizes the TanStack Virtual library. For further configuration details please see the following [documentation](https://tanstack.com/virtual/v3/docs/api/virtualizer) for all available props that may be passed in with the `virtual` object. To maximize performance virtualization for the SelectInput component is configured by default to use fixed sizing based on an option item element height of `38px`. If your item height remains fixed but needs to be updated, pass in `estimateSize` and set to the new height, i.e., `estimateSize: () => height value`. If the item height is unknown on render enable dynamic sizing by passing in `dynamicSizing: true`. Here are the following default settings: - `dynamicSizing` : When `true` each option item element is dynamically measured on render. Note: scrolling performance may not be as smooth (default value is `false`). - `estimateSize` : Sets item height when using fixed sizing. When using dynamic sizing, to help with scroll performance, set this to the largest possible height of the item elements (default value is `38`). - `overscan` : Number of element items to render above and below the visible area (default value is `5`). ```jsx live () => { const defaultOptionCount = 5000; const withSectionHeaders = false; const optionNumberForm = useForm({ defaultValues: { optionCount: defaultOptionCount, }, }); const selectInputForm = useForm(); const [options, setOptions] = React.useState(); const generateOptions = (count) => { const options = Array.from(Array(Number(count)).keys()).map((i) => { const optionLabelValue = `Option ${i + 1}`; if (withSectionHeaders) { return { section: `Option ${i + 1} Header`, items: [ { label: `${optionLabelValue} A`, value: `${optionLabelValue}_A` }, { label: `${optionLabelValue} B`, value: `${optionLabelValue}_B` }, ], }; } return { label: optionLabelValue, value: optionLabelValue }; }); setOptions(options); }; useEffect(() => { generateOptions(defaultOptionCount); }, []); return ( <React.Fragment> <FormProvider state={optionNumberForm} onSubmit={({ optionCount }) => generateOptions(optionCount)} > <Layout.Group alignItems="bottom"> <TextInput label="Set Number of Dropdown Options" placeholder="Enter number" model="optionCount" mask="numeric" maskConfig={{ isAllowed: ({ floatValue }) => { const value = floatValue || 0; return value <= 100000; }, }} /> <Button type="submit">Update Options</Button> <Button variant="outline" type="button" onClick={() => { optionNumberForm.reset(); selectInputForm.reset(); generateOptions(defaultOptionCount); }} > Reset </Button> </Layout.Group> </FormProvider> <FormProvider state={selectInputForm}> <SelectInput css={{ 'abyss-select-input-multi-root': { marginTop: '$lg' } }} label="SelectInput with Virtualization" placeholder={`Includes ${options ? options.length : 0} options`} model="selectWithVirtual" isClearable isSearchable options={options} virtual retainSectionHeader={withSectionHeaders} /> <SelectInput label="SelectInput without Virtualization" placeholder={`Includes ${options ? options.length : 0} options`} model="selectWithoutVirtual" isClearable isSearchable options={options} retainSectionHeader={withSectionHeaders} /> </FormProvider> </React.Fragment> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={SelectInput} rows={[ { name: 'label', type: 'string', description: 'Select list label', }, { name: 'hideLabel', type: 'boolean', description: 'Flag to show or hide label', }, { name: 'helper', type: 'node | string', description: 'Helper element next to label', }, { name: 'model', type: 'string', description: 'Unique identifier used for FormProvider', }, { name: 'placeholder', type: 'string', description: 'Short description displayed in the select list before the user selects a value', }, { name: 'errorMessage', type: 'string', description: 'Error message to be displayed below the select input field', }, { name: 'subText', type: 'string', description: 'Text displayed below the select input field', }, { name: 'descriptorsDisplay', type: '"row" | "column"', description: 'Set the orientation of descriptor content located below the select input field', }, { name: 'maxListHeight', type: 'number | string', description: 'Set the max height of the option list.', }, { name: 'onChange', type: 'function', description: 'Callback fired every time the selection value changes. The component provides two arguments to this callback: value (the new selected value) and selectedOption (an object representing the selected option properties).', }, { name: 'onClear', type: 'function', description: 'Callback fired when user clicks the clear button. The isClearable property must be set to true', }, { name: 'onFocus', type: 'function', description: 'Callback fired every time the component is focused', }, { name: 'onBlur', type: 'function', description: 'Callback fired every time the component is unfocused', }, { name: 'onKeyDown', type: 'function', description: 'Callback fired every time a key is pressed while focused in the component', }, { name: 'onPaste', type: 'function', description: 'Callback fired every time something is pasted into the component', }, { name: 'onInputChange', type: 'function', description: 'Callback fired when the value of the search text input changes.', }, { name: 'validators', type: 'object', description: 'Set rules for the input field to be valid', }, { name: 'isDisabled', type: 'boolean', description: 'Flag to enable/disable the select list. If true, the select list will be disabled', }, { name: 'isClearable', type: 'boolean', description: 'Flag to enable/disable the ability for a user to clear the select list', }, { name: 'isSearchable', type: 'boolean', description: 'Flag to enable/disable the select list search/filter feature', }, { name: 'isLoading', type: 'boolean', description: 'Flag to enable/disable the loading state of the select list.', }, { name: 'options', type: 'object[]', description: 'List of options selectable in the select list input. { label: string, value: string }', }, { name: 'fuseConfig', type: 'shape', description: 'Configs for Fuse', }, { name: 'value', type: 'string', description: 'Option value or list of option values selected in the select list input.', }, { name: 'width', type: 'string', description: 'Width of the select list', }, { name: 'labelKey', type: 'string', description: 'Set the key value of the label in the options list. Defaults to "label"', }, { name: 'valueKey', type: 'string', description: 'Set the key value of the value in the options list. Defaults to "value"', }, { name: 'inputLeftElement', type: 'ReactNode', description: 'Add element to left of inside select input', }, { name: 'inputRightElement', type: 'ReactNode', description: 'Add element to right of inside select input', }, { name: 'leftAddOnDescription', type: 'string', description: 'Screen reader description for the left add-on', }, { name: 'rightAddOnDescription', type: 'string', description: 'Screen reader description for the right add-on', }, { name: 'enableOutsideScroll', type: 'boolean', description: 'Flag to enable scroll on all outside elements', }, { name: 'virtual', type: 'object | boolean', description: 'Adds virtualization to option item drop-down list', }, { name: 'debounceTime', type: 'number', description: 'Set the length of time that the search should debounce by (in milliseconds)', }, { name: 'apiFiltering', type: 'function', description: 'Api Filter used for fetching search results from an api', }, { name: 'customRender', type: 'function', description: 'Custom render for option items', }, { name: 'keys', type: 'array[string]', description: 'Keys used by Fuse', default: "['value', 'label']", }, { name: 'ref', type: 'object', description: 'Add a ref to the input element; includes clearInput method', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={SelectInput} rows={[ { name: 'select-input-root', description: 'Root element', }, { name: 'select-input-label', description: 'Label', }, { name: 'select-input-input-container', description: 'Input and option list container', }, { name: 'select-input-input', description: 'Input', }, { name: 'select-input-left-element-wrapper', description: 'Wrapper for left input element', }, { name: 'select-input-left-element', description: 'Input left element', }, { name: 'select-input-right-element-wrapper', description: 'Wrapper for right input element', }, { name: 'select-input-right-element', description: 'Input right element', }, { name: 'select-input-clear', description: 'Clear button', }, { name: 'select-input-element-wrapper', description: 'Select input clear/icon element wrapper', }, { name: 'select-input-loading-container', description: 'Loading spinner container', }, { name: 'select-input-loading-spinner', description: 'Loading spinner', }, { name: 'select-input-icon-container', description: 'Chevron icon container', }, { name: 'select-input-icon', description: 'Chevron icon', }, { name: 'select-input-descriptors', description: 'Descriptor', }, { name: 'select-input-option-list', description: 'Option list', }, { name: 'select-input-no-options', description: 'No options list item', }, { name: 'select-input-section', description: 'Option list section header item', }, { name: 'select-input-option', description: 'Option list item', }, { name: 'select-input-option-content', description: 'Option container', }, { name: 'select-input-option-icon', description: 'Selected check icon', }, { name: 'select-input-portal-container', description: 'Select input portal container', }, ]} /> ``` </Tab> <Tab label="Accessibility"> A combobox is a widget made up of the combination of two distinct elements: 1) a single-line textbox, and 2) an associated pop-up element for helping users set the value of the textbox. The popup may be a listbox, grid, tree, or dialog. Many implementations also include a third optional element -- a graphical button adjacent to the textbox, indicating the availability of the popup. Activating the button displays the popup if suggestions are available. Adheres to the <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/combobox/">Combo box WAI-ARIA design pattern</ExitLink>. Listed Below are example use cases: - <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-select-only/"> Select-Only Combobox Example </ExitLink> - <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-list/"> Editable Combobox With List Autocomplete Example </ExitLink> - <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/listbox/examples/listbox-grouped/"> Listbox Example with Grouped Options </ExitLink> ```jsx live () => { const form = useForm({ defaultValues: { framework: 'react', }, }); return ( <FormProvider state={form}> <SelectInput label="Pick free menu option" placeholder="Pick one" model="framework" isClearable isSearchable options={[ { value: '1', label: 'Nothing' }, { section: 'Drinks', items: [ { value: '10', label: 'Water' }, { value: '20', label: 'Soft drinks' }, { value: '30', label: 'Beer', isDisabled: true }, ], }, { section: 'Entrees', items: [ { value: '11', label: 'Hamburger' }, { value: '21', label: 'Chicken Tenders' }, ], }, { section: 'Sides', items: [ { value: '31', label: 'French Fries' }, { value: '41', label: 'Onion Rings' }, ], }, ]} validators={{ required: true }} /> </FormProvider> ); }; ``` ```jsx render <Docs.AccessibilityTable title="Textbox" rows={[ { name: 'Down Arrow', description: 'If the listbox is displayed: Moves focus to the second suggested value. Note that the first value is automatically selected. If the listbox is not displayed: opens the listbox and moves focus to the first value.', }, { name: 'Up Arrow', description: 'If the listbox is displayed, moves focus to the last suggested value. If the listbox is not displayed, opens the listbox and moves focus to the last value.', }, { name: 'Alt + Down Arrow', description: 'Opens the listbox without moving focus or changing selection.', }, { name: 'Enter', description: 'If the listbox is displayed and the first option is automatically selected: Sets the textbox value to the content of the selected option. Closes the listbox.', }, { name: 'Esc', description: 'Clears the textbox. If the listbox is displayed, closes it.', }, { name: 'Supported Keystrokes', description: 'Supported keystrokes use character matching functionality to display matched values in the Listbox.', }, ]} /> ``` ```jsx render <Docs.AccessibilityTable title="Listbox" rows={[ { name: 'Enter', description: 'Sets the textbox value to the content of the focused option in the listbox. Closes the listbox. Sets focus on the textbox.', }, { name: 'Esc', description: 'Closes the listbox. Sets focus on the textbox. Clears the textbox.', }, { name: 'Down Arrow', description: 'Moves focus to the next option. If focus is on the last option, moves focus to the first option.', }, { name: 'Up Arrow', description: 'Moves focus to the previous option. If focus is on the first option, moves focus to the last option.', }, { name: 'Right Arrow', description: 'Moves focus to the textbox and moves the editing cursor one character to the right.', }, { name: 'Left Arrow', description: 'Moves focus to the textbox and moves the editing cursor one character to the left.', }, { name: 'Home', description: 'Moves focus to the textbox and places the editing cursor at the beginning of the field.', }, { name: 'End', description: 'Moves focus to the textbox and places the editing cursor at the end of the field.', }, ]} /> ``` <h2> BrAT Bugs </h2> - Issues below reproduced in WAI-ARIA <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-list/">Editable Combobox With List Autocomplete Example</ExitLink> - MacOS/Safari does not announce anything related to listbox (expanded, collapsed, options) - This makes the result count somewhat more helpful - NVDA does not announce aria-selected even when applied - JAWS announces each entries as selected which is correct based upon the standard <h2> Notes </h2> - Hiding the label negatively impacts accessibility. - Labels are required for fields - Hiding labels requires sighted users to guess their name - This can increase the difficulty of speech recognition when speaking the command to "click" the field - Supplemental information is supplied from the downshift library </Tab> --- id: select-input-multi category: Forms title: SelectInputMulti description: Allows users to select multiple values from a provided list of options. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=3697-26104 --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="SelectInputMulti"></Docs.V2MigrationBanner> ``` ```jsx import { SelectInputMulti } from '@uhg-abyss/web/ui/SelectInputMulti'; ``` ```jsx sandbox { component: 'SelectInputMulti', inputs: [ { prop: 'label', type: 'string', defaultValue: 'Sandbox', }, { prop: 'placeholder', type: 'string', }, { prop: 'subText', type: 'string', }, { prop: 'width', type: 'string', }, { prop: 'maxListHeight', type: 'string', }, { prop: 'hideLabel', type: 'boolean', }, { prop: 'isDisabled', type: 'boolean', }, { prop: 'isSearchable', type: 'boolean', }, { prop: 'selectAll', type: 'boolean', }, { prop: 'highlighted', type: 'boolean', defaultValue: false, }, ], } () => { const [value, setValue] = React.useState(['alpine']); const onSubmit = () => { console.log('value', value); }; return ( <React.Fragment> <SelectInputMulti label="Your favorite framework/library" placeholder="Pick one" value={value} onChange={setValue} isSearchable options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> <Button onClick={onSubmit} style={{ marginTop: '15px' }}> Submit </Button> </React.Fragment> ); }; ``` ## Usage Use the `options` prop to supply the options that can be selected. `options` is an array of objects, where each object should have two properties: - `value`, which is a unique identifier for the option - `label`, which is how the option will be displayed in the list Sections can also be specified, in which case the section object should have `section` and `items` properties instead of `label` and `value` (See [Section Headers](#section-headers) for more details). ## useForm (recommended) Using the `useForm` hook lets the DOM handle form data. ```jsx live () => { const form = useForm({ defaultValues: { frameworks: ['react'], }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <SelectInputMulti label="Your favorite framework/library" placeholder="Pick one" model="frameworks" isSearchable options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} validators={{ required: true }} /> <Button type="submit" style={{ marginTop: '15px' }}> Submit </Button> </FormProvider> ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [value, setValue] = React.useState(['alpine']); const onSubmit = () => { console.log('value', value); }; const onChange = (newValue, selectedOption) => { console.log('onChange newValue:', newValue); console.log('onChange selectedOption', selectedOption); setValue(newValue); }; return ( <React.Fragment> <SelectInputMulti label="Your favorite framework/library" placeholder="Pick one" value={value} onChange={onChange} isSearchable options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> <Button onClick={onSubmit} style={{ marginTop: '15px' }}> Submit </Button> </React.Fragment> ); }; ``` ## Section headers To create section headers in the list, pass objects into the `options` array that have the `section` and `items` properties. `section` specifies the name of the section, which will be bolded and un-selectable, while `items` should contain the options within that section (with the same `value`/`label` format as normal), which will appear indented. The `retainSectionHeader` prop can be passed in to retain the corresponding section headers in the results when searching. ```jsx [ { value: 'id1', label: 'Option 1' }, { value: 'id2', label: 'Option 2' }, { section: 'Section Header', items: [ { value: 'id3', label: 'Sub-section Option 1' }, { value: 'id4', label: 'Sub-section Option 2' }, ... ], }, ... ] ``` ```jsx live () => { const [value, setValue] = React.useState([]); return ( <SelectInputMulti label="Section Headers Example" placeholder="Pick one" value={value} onChange={setValue} isSearchable retainSectionHeader options={[ { value: '1', label: 'This option is not under any section' }, { section: 'Section Header', items: [ { value: '11', label: 'Option 1' }, { value: '21', label: 'Option 2' }, ], }, { section: 'Other Section Header', items: [ { value: '31', label: 'Option 3' }, { value: '41', label: 'Option 4' }, ], }, ]} /> ); }; ``` ## Hide chips Use the `hideChips` prop to display the selected items as a comma separated list. Once the list exceeds the available space it will display, `[selection count] Selected`. If all available options are selected, `All Selected ([total count])`, will be displayed. Default is set to `false` and selections will display as chips. ```jsx live () => { const [value, setValue] = React.useState(['alpine']); return ( <SelectInputMulti label="Hide Chips" placeholder="Choose an option" value={value} onChange={setValue} isSearchable options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} hideChips /> ); }; ``` ## Selected items container This example demonstrates how to display the selected items within a separate container outside of the SelectInputMulti. ```jsx live () => { const [value, setValue] = React.useState([ 'react', 'ng', 'svelte', 'vue', 'alpine', 'ember', 'stimulus', 'preact', ]); const options = [ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]; return ( <Layout.Stack grow space={15}> <SelectInputMulti label="Your favorite framework/library" placeholder="Pick one" value={value} onChange={setValue} isSearchable options={options} hideChips /> <Layout.Stack grow space={4}> <Label>Selected Items Container</Label> <Box color="$white" height={100} padding="$sm" css={{ 'abyss-box-root': { border: '1px solid $gray6', borderRadius: '4px', overflow: 'auto', }, }} tabIndex="0" > <ul> {value.map((val, index) => ( <li key={`multi_item_${index}`} style={{ marginBottom: '8px', fontSize: '14px' }} > {options.map((option) => { if (option.value === val) return option.label; })} </li> ))} </ul> </Box> </Layout.Stack> </Layout.Stack> ); }; ``` ## Add elements inside input Use the `inputLeftElement` and `inputRightElement` props to add elements to the inside of the select input multi field. The recommended usage is for inserting icons. These are considered decorative and do not need to be exposed to screen readers. That said, please note that icons should _not_ provide any information that is not also conveyed in a screen-readable way. For example, an (!) icon to indicate errors needs to be accompanied by `aria-invalid`. If icons are used to convey additional information, use the `inputLeftElementDescription` and `inputRightElementDescription` props to provide a description for screen readers. See the [Validation](#validation) section below for an example on how to incorporate with validation and display error/success states with icons. ```jsx live () => { const [value, setValue] = useState(['1']); return ( <SelectInputMulti label="Inside Elements" value={value} onChange={setValue} options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} isSearchable inputLeftElement={<IconSymbol icon="star" size="20px" color="$gray6" />} inputRightElement={<IconSymbol icon="check" size="20px" />} inputLeftElementDescription="Star Icon" inputRightElementDescription="Checkmark Icon" /> ); }; ``` ## Label The `label` prop is required. To hide the label use the `showLabel` prop to show or hide the label. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <SelectInputMulti label="Active Label" placeholder="Active Label" model="activeLabel" options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> <SelectInputMulti label="Hidden Label" placeholder="Hidden Label" model="hiddenLabel" hideLabel css={{ 'abyss-select-input-root': { marginTop: '15px' } }} options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> <Button type="submit" css={{ marginTop: '15px' }}> Submit </Button> </FormProvider> ); }; ``` ## Search label The label of the text input within the opened menu is `Search` by default. Use the `searchLabel` prop to customize this label. Only relevant if `isSearchable` is `true`. You can also customize the placeholder text in the text input with the `searchPlaceholder` prop. ```jsx live () => { const form = useForm({ defaultValues: { frameworks: ['react'], }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <SelectInputMulti label="Your favorite framework/library" searchLabel="Custom Search Label" searchPlaceholder="Custom Placeholder Text..." model="frameworks" isSearchable options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> <Button type="submit" style={{ marginTop: '15px' }}> Submit </Button> </FormProvider> ); }; ``` ## Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip) or a [Popover](/web/ui/popover). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; const options = [ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]; return ( <FormProvider state={form}> <SelectInputMulti label="Default Helper" helper="This is a tooltip" model="helper-tooltip" options={options} /> <SelectInputMulti label="Custom Helper" helper={ <Popover title="Custom Helper" content="This is a popover with a custom icon" > <IconSymbol icon="help" variant="outlined" color="$success1" size="$sm" /> </Popover> } model="helper-custom" options={options} validators={{ required: true }} /> <Button type="submit" css={{ marginTop: '15px' }}> Submit </Button> </FormProvider> ); }; ``` ## Disabled Set the `isDisabled` prop to `true` to disable the select list input field so users cannot select a value. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <SelectInputMulti label="Disabled" isDisabled={true} model="disabled" options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> <Button type="submit" style={{ marginTop: '15px' }}> Submit </Button> </FormProvider> ); }; ``` ## Disable option items Disable an individual option item by setting the `isDisabled` key to `true` within the object. ```jsx live () => { const [value, setValue] = React.useState(['alpine']); const onSubmit = () => { console.log('value', value); }; return ( <React.Fragment> <SelectInputMulti label="Your favorite framework/library" placeholder="Pick one" value={value} onChange={setValue} isSearchable options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular', isDisabled: true }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> <Button onClick={onSubmit} style={{ marginTop: '15px' }}> Submit </Button> </React.Fragment> ); }; ``` ## SubText Use the `subText` prop to display helpful text below the select list input field. ```jsx live () => { const form = useForm({ defaultValues: { 'sub-text': ['1'], }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <SelectInputMulti label="SubText" subText="Sub Text Example" model="sub-text" validators={{ required: true }} options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> <Button type="submit" style={{ marginTop: '15px' }}> Submit </Button> </FormProvider> ); }; ``` ## Descriptors display Use the `descriptorsDisplay` prop to set the orientation of the error message and subtext descriptor content. Available variants include 'column' and 'row'. The default is set to 'row'. Use the [FormProvider](/web/ui/form-provider#descriptors-display) and `descriptorsDisplay` to set the descriptors orientation across an entire form. Note: The errorMessage prop does not work with useForm and is only applicable within our form input components when useState is being utilized. See the [useForm Docs](/web/hooks/use-form#set-error) for example use cases with useForm. ```jsx live () => { const [value, setValue] = useState(); return ( <SelectInputMulti value={value} onChange={setValue} options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} isSearchable label="Descriptors Display" subText="Subtext Message" errorMessage="Error Message" descriptorsDisplay="column" /> ); }; ``` ## Loading Use the `isLoading` prop to display a loading spinner in place of the drop-down options list. This is useful when loading in the SelectInputMulti options. ```jsx live () => { const [isLoading, setIsLoading] = useState(true); const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( <Layout.Stack grow> <FormProvider state={form} onSubmit={onSubmit}> <SelectInputMulti label="Loading" placeholder={isLoading ? 'Loading...' : 'Select Options'} isLoading={isLoading} model="loading" options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> </FormProvider> <Button onClick={() => setIsLoading(!isLoading)} style={{ marginTop: '15px' }} > Toggle Loading </Button> </Layout.Stack> ); }; ``` ## Searchable Use the `isSearchable` prop to display an input field for the user to search/filter the list of options this is located inside the dropdown. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <SelectInputMulti label="Searchable" model="searchable" isSearchable placeholder="Searchable" options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> <Button type="submit" style={{ marginTop: '15px' }}> Submit </Button> </FormProvider> ); }; ``` ### Fuse.js When applying `isSearchable` to SelectInputMulti, it will fuzzy filter your results using the <ExitLink href="https://fusejs.io">Fuse.js</ExitLink> library. What is fuzzy searching?... Generally speaking, fuzzy searching (more formally known as approximate string matching) is the technique of finding strings that are approximately equal to a given pattern (rather than exactly). ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <SelectInputMulti placeholder="Search..." model="search" label="Fuse Default Search" isSearchable options={[ { value: 'react', label: 'React', }, { value: 'ng', label: 'Angular', }, { value: 'svelte', label: 'Svelte', }, { value: 'preact', label: 'Preact', }, ]} /> </FormProvider> ); }; ``` ### Fuse keys The `keys` prop allows you to specify the values from the specific keys within your `options` object to search against. This feature accommodates nested paths, prioritizes certain fields with weighted search, and can handle searches within arrays of objects. The default search keys are `['label', 'value']`. For example, if you wanted to search on the `label` and `tags` values in your object, you would pass in `keys={['label', 'tags']}`. ```javascript { value: "react", label: "React", tags: ['jsx', 'virtual dom', 'facebook'] } ``` ```jsx live () => { const form = useForm({}); return ( <FormProvider state={form}> <SelectInputMulti label="Fuse Keys Search" placeholder="Pick one" keys={['label', 'tags']} model="framework" isClearable isSearchable options={[ { value: 'react', label: 'React', tags: ['jsx', 'virtual dom', 'facebook'], }, { value: 'ng', label: 'Angular', tags: ['typescript', 'directives', 'google'], }, { value: 'svelte', label: 'Svelte', tags: ['compile-time', 'no virtual dom', 'rich harris'], }, ]} /> </FormProvider> ); }; ``` ### Custom Fuse configurations You can customize the fuse filter by following the documentation on <ExitLink href="https://fusejs.io/api/options.html">Fuse</ExitLink> and passing your configurations into the `fuseConfig` prop. For example, if you wanted to adjust the <ExitLink href="https://www.fusejs.io/api/options.html#threshold">threshold</ExitLink> to `0` so the search criteria requires an exact match, you would pass in the following object. The default threshold is `0.1`. ```jsx const customFuseConfig = { threshold: 0, // exact match }; ``` ```jsx live () => { const [sliderValue, setSliderValue] = useState(0); const form = useForm(); const customFuseConfig = { threshold: sliderValue / 100, }; return ( <FormProvider state={form}> <SelectInputMulti label="Custom Fuse Threshold Config" placeholder="Pick one" keys={['label']} model="framework" isClearable isSearchable fuseConfig={customFuseConfig} options={[ { value: 'react', label: 'React', }, { value: 'ng', label: 'Angular', }, { value: 'svelte', label: 'Svelte', }, { value: 'preact', label: 'Preact', }, ]} /> <Slider css={{ 'abyss-slider-label': { marginTop: '20px', }, '&.abyss-slider-root': { width: '85%', marginLeft: 'auto', marginRight: 'auto', }, }} label="Search Threshold" value={sliderValue} onChange={setSliderValue} step={20} showMarks marks={[ { value: 0, label: 'Exact Match' }, { value: 20, label: '.2' }, { value: 40, label: '.4' }, { value: 60, label: '.6' }, { value: 80, label: '.8' }, { value: 100, label: 'Match Anything' }, ]} /> </FormProvider> ); }; ``` ## onInputChange The `onInputChange` prop is an event handler called when the value of the filter text input changes while searching. The callback returns the current search value of the input. ```jsx live () => { const form = useForm(); const onInputChange = (value) => { console.log('value', value); }; return ( <FormProvider state={form}> <SelectInputMulti label="onInputChange" hideLabel placeholder="Search..." model="onInputChange" isSearchable options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} onInputChange={onInputChange} /> </FormProvider> ); }; ``` ## API filtering with debounce Use the `apiFiltering` prop to override the fuse.js filtering and supply a custom function to make asynchronous calls to an API. Both current value and selected value results will be passed to the apiFiltering callback. The results from your API should be passed into the `options` prop. If `debounceTime` is not passed, a default debounce time of 1000ms will be applied. In the example below, search by the string `united` to see results. ```jsx live () => { const [results, setResults] = useState([]); const [loading, setLoading] = useState(false); const form = useForm(); const handleSearch = (data) => { console.log('Searched', data); }; const apiFilter = (currentValue, selectedValues) => { console.log('currentValue', currentValue); console.log('selectedValue', selectedValues); setLoading(true); utils.useSearchInputMockApi(currentValue).then((response) => { setLoading(false); setResults(response); }); }; return ( <FormProvider state={form}> <SelectInputMulti placeholder="Search..." model="apiFiltering" label="Api Filtering" isSearchable options={results} isLoading={loading} debounceTime={1200} apiFiltering={apiFilter} selectAll /> </FormProvider> ); }; ``` ## Styling option items To style individual option items add the `className` property with a custom class name to the option object you'd like to target. Just as you would target a static abyss class you can target this custom class using the `css` prop. ```jsx live () => { const [value, setValue] = React.useState([]); return ( <SelectInputMulti label="Styling Option Items" placeholder="Pick one" value={value} onChange={setValue} options={[ { value: 'javascript', label: 'Javascript', className: 'tier-one' }, { value: 'react', label: 'React', className: 'tier-two' }, { value: 'ng', label: 'Angular', className: 'tier-two' }, { value: 'vue', label: 'Vue', className: 'tier-two' }, { value: 'python', label: 'Python', className: 'tier-one' }, { value: 'django', label: 'Django', className: 'tier-two' }, { value: 'flask', label: 'Flask', className: 'tier-two' }, ]} css={{ 'tier-one': { '.abyss-select-input-multi-option-label': { fontWeight: '$bold' }, }, 'tier-two': { '.abyss-checkbox-container': { marginLeft: '$md' }, }, }} /> ); }; ``` ## Custom render Use the `customRender` prop to customize the render of each option item. If [Section Headers](#section-headers) are used they will also be handled by this function. `customRender` provides the item object as the first parameter and the items state as the second. ```jsx live () => { const [value, setValue] = useState(); const customRender = (item, state) => { const defaultSettings = { icon: 'cancel', color: '$error1', variant: 'error', }; const getSettings = () => { const { status } = (item.items && item.items[0]) || item; if (status === 'active') { return { icon: 'check_circle_outline', color: '$success1', variant: 'success', }; } return defaultSettings; }; const { icon, color, variant } = getSettings(); if (!!item.section) { return ( <Layout.Group> <span>{item.section}</span> <IconSymbol icon={icon} color={color} /> </Layout.Group> ); } return <Badge variant={variant}>{item.label}</Badge>; }; return ( <SelectInputMulti label="Custom Render" placeholder="Pick one" value={value} onChange={setValue} isSearchable maxListHeight={300} customRender={customRender} options={[ { section: 'Active Options', items: [ { value: 'option_1', label: 'Option 1', status: 'active' }, { value: 'option_2', label: 'Option 2', status: 'active' }, { value: 'option_3', label: 'Option 3', status: 'active' }, ], }, { section: 'Inactive Options', items: [ { value: 'option_4', label: 'Option 4', status: 'inactive' }, { value: 'option_5', label: 'Option 5', status: 'inactive' }, { value: 'option_6', label: 'Option 6', status: 'inactive' }, ], }, ]} /> ); }; ``` ## Width Use the `width` prop to set the width of the select list. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <SelectInputMulti label="Default Width" placeholder="Width: Default" model="widthDefault" options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> <SelectInputMulti label="Width 75%" width="75%" placeholder="Width: 75%" model="width75" options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> <SelectInputMulti label="Width" placeholder="Width: 300px" width="300px" model="width300" options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, ]} /> <Button type="submit" style={{ marginTop: '15px' }}> Submit </Button> </FormProvider> ); }; ``` ## MaxListHeight Use `maxListHeight` to set the height of the dropdown list. ```jsx live () => { const form = useForm({ defaultValues: { maxListHeight: ['2'], }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <SelectInputMulti label="Single Select Clearable" placeholder="Single Select Clearable" model="maxListHeight" maxListHeight="100px" options={[ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, { label: 'Option 4', value: '4' }, { label: 'Option 5', value: '5' }, { label: 'Option 6', value: '6' }, { label: 'Option 7', value: '7' }, { label: 'Option 8', value: '8' }, ]} /> </FormProvider> ); }; ``` ## Select all By setting the `selectAll` property to `true`, you can make a "Select All" option visible at the top of the dropdown. When selected, all options will be selected. When deselected, all options will be deselected. Note: <br />When the `selectAll` prop is enabled, it is recommended not to manually include an object with `value: 'all'` in the options list. This value is reserved for the "Select All" functionality, and manually including it may lead to unexpected behavior. ```jsx live () => { const [value, setValue] = React.useState(['alpine']); const onSubmit = () => { console.log('value', value); }; return ( <React.Fragment> <SelectInputMulti label="Your favorite framework/library" placeholder="Pick one" value={value} onChange={setValue} selectAll isSearchable options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> <Button onClick={onSubmit} style={{ marginTop: '15px' }}> Submit </Button> </React.Fragment> ); }; ``` ## Label/value key Use the `valueKey` and `labelKey` props to change the key thats used to read the labels and values from the options list. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <SelectInputMulti label="Label/Value Keys" placeholder="Label/Value Keys" model="keys" labelKey="newLabel" valueKey="newValue" options={[ { newLabel: 'Option 1', newValue: '1' }, { newLabel: 'Option 2', newValue: '2' }, { newLabel: 'Option 3', newValue: '3' }, ]} /> </FormProvider> ); }; ``` ## Validation Use the validators prop to set rules for the field to be valid. ```jsx live () => { const form = useForm(); const { errors, isSubmitted, isSubmitSuccessful } = form.formState; const getIconProps = useCallback( (model) => { if (!isSubmitted) return {}; let iconProps = {}; if (!!errors[model]) { iconProps = { icon: 'error', color: '$error1', size: '18px' }; } if (isSubmitSuccessful) { iconProps = { icon: 'check', color: '$success1', size: '18px' }; } const isEmpty = Object.keys(iconProps).length === 0; return !isEmpty ? { inputRightElement: <IconSymbol {...iconProps} /> } : {}; }, [isSubmitted, isSubmitSuccessful] ); const options = [ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' }, { label: 'Option 4', value: '4' }, { label: 'Option 5', value: '5' }, ]; return ( <FormProvider state={form}> <SelectInputMulti label="Required Default Message" model="required" isSearchable options={options} {...getIconProps('required')} validators={{ required: true }} /> <SelectInputMulti label="Required Custom Message" model="custom-required" isSearchable options={options} validators={{ required: 'Custom Error Message' }} /> <SelectInputMulti label="Custom Validators" model="validate" isSearchable options={options} validators={{ required: true, validate: { moreThanTwo: (v) => { return ( v.length >= 2 || 'Should include a minimum of two selections' ); }, }, }} /> <Button type="submit" style={{ marginTop: 15 }}> Submit </Button> </FormProvider> ); }; ``` ## Highlighted Use the `highlighted` prop to enable the background color for the input. You can use `FormProvider` and `highlighted` to enable the color to appear if validation is required. ```jsx live () => { const [value, setValue] = useState(); return ( <SelectInputMulti label="Your favorite framework/library" placeholder="Pick one" value={value} onChange={setValue} isSearchable highlighted options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> ); }; ``` ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit} highlighted> <SelectInputMulti label="Your favorite framework/library" placeholder="Pick one" model="frameworks" isSearchable options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} validators={{ required: true }} /> <Button type="submit" style={{ marginTop: 15 }}> Submit </Button> </FormProvider> ); }; ``` ## Enable outside scroll Set the `enableOutsideScroll` prop to `true` to enable scroll outside of the search input component while the option list is open. Default is set to `false`. ```jsx live () => { const [value, setValue] = React.useState(['alpine']); const onSubmit = () => { console.log('value', value); }; return ( <React.Fragment> <SelectInputMulti label="Your favorite framework/library" placeholder="Pick one" value={value} onChange={setValue} enableOutsideScroll isSearchable options={[ { value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }, { value: 'svelte', label: 'Svelte' }, { value: 'vue', label: 'Vue' }, { value: 'alpine', label: 'Alpine' }, { value: 'ember', label: 'Ember' }, { value: 'stimulus', label: 'Stimulus' }, { value: 'preact', label: 'Preact' }, ]} /> <Button onClick={onSubmit} style={{ marginTop: '15px' }}> Submit </Button> </React.Fragment> ); }; ``` ## Virtualization Use the `virtual` prop to add virtualization and improve performance when working with larger data sets. Virtualization leverages the `useVirtualization` hook which utilizes the TanStack Virtual library. For further configuration details please see the following [documentation](https://tanstack.com/virtual/v3/docs/api/virtualizer) for all available props that may be passed in with the `virtual` object. To maximize performance virtualization for the SelectInputMulti component is configured by default to use fixed sizing based on an option item element height of `40px`. If your item height remains fixed but needs to be updated, pass in `estimateSize` and set to the new height, i.e., `estimateSize: () => height value`. If the item height is unknown on render enable dynamic sizing by passing in `dynamicSizing: true`. Here are the following default settings: - `dynamicSizing` : When `true` each option item element is dynamically measured on render. Note: scrolling performance may not be as smooth (default value is `false`). - `estimateSize` : Sets item height when using fixed sizing. When using dynamic sizing, to help with scroll performance, set this to the largest possible height of the item elements (default value is `40`). - `overscan` : Number of element items to render above and below the visible area (default value is `5`). ```jsx live () => { const defaultOptionCount = 5000; const withSectionHeaders = false; const optionNumberForm = useForm({ defaultValues: { optionCount: defaultOptionCount, }, }); const selectInputForm = useForm(); const [options, setOptions] = React.useState(); const generateOptions = (count) => { const options = Array.from(Array(Number(count)).keys()).map((i) => { const optionLabelValue = `Option ${i + 1}`; if (withSectionHeaders) { return { section: `Option ${i + 1} Header`, items: [ { label: `${optionLabelValue} A`, value: `${optionLabelValue}_A` }, { label: `${optionLabelValue} B`, value: `${optionLabelValue}_B` }, ], }; } return { label: optionLabelValue, value: optionLabelValue }; }); setOptions(options); }; useEffect(() => { generateOptions(defaultOptionCount); }, []); return ( <React.Fragment> <FormProvider state={optionNumberForm} onSubmit={({ optionCount }) => generateOptions(optionCount)} > <Layout.Group alignItems="bottom"> <TextInput label="Set Number of Dropdown Options" placeholder="Enter number" model="optionCount" mask="numeric" maskConfig={{ isAllowed: ({ floatValue }) => { const value = floatValue || 0; return value <= 100000; }, }} /> <Button type="submit">Update Options</Button> <Button variant="outline" type="button" onClick={() => { optionNumberForm.reset(); selectInputForm.reset(); generateOptions(defaultOptionCount); }} > Reset </Button> </Layout.Group> </FormProvider> <FormProvider state={selectInputForm}> <SelectInputMulti css={{ 'abyss-select-input-multi-root': { marginTop: '$lg' } }} label="SelectInputMulti with Virtualization" placeholder={`Includes ${options ? options.length : 0} options`} model="selectWithVirtual" isSearchable options={options} virtual retainSectionHeader={withSectionHeaders} /> <SelectInputMulti label="SelectInputMulti without Virtualization" placeholder={`Includes ${options ? options.length : 0} options`} model="selectWithoutVirtual" isSearchable options={options} retainSectionHeader={withSectionHeaders} /> </FormProvider> </React.Fragment> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={SelectInputMulti} rows={[ { name: 'label', type: 'string', description: 'Select list label', }, { name: 'searchLabel', type: 'string', description: 'Label for the search input in the isSearchable variant', default: 'Search', }, { name: 'hideLabel', type: 'boolean', description: 'Flag to show or hide label', }, { name: 'helper', type: 'node | string', description: 'Helper element next to label', }, { name: 'model', type: 'string', description: 'Unique identifier used for FormProvider', }, { name: 'placeholder', type: 'string', description: 'Short description displayed in the select list before the user selects a value', }, { name: 'searchPlaceholder', type: 'string', description: 'Short description displayed in the search input in the isSearchable variant', default: 'Filter Options', }, { name: 'errorMessage', type: 'string', description: 'Error message to be displayed below the select input field', }, { name: 'subText', type: 'string', description: 'Text displayed below the select input field', }, { name: 'descriptorsDisplay', type: '"row" | "column"', description: 'Set the orientation of descriptor content located below below the select input field', }, { name: 'onChange', type: 'function', description: 'Callback fired every time the value changes. The component provides two arguments to this callback: value (the new selected value(s)) and selectedOption (an object representing the selected option(s) properties).', }, { name: 'onFocus', type: 'function', description: 'Callback fired every time the component is focused', }, { name: 'onBlur', type: 'function', description: 'Callback fired every time the component is unfocused', }, { name: 'onKeyDown', type: 'function', description: 'Callback fired every time a key is pressed while focused in the component', }, { name: 'onPaste', type: 'function', description: 'Callback fired every time something is pasted into the component', }, { name: 'onInputChange', type: 'function', description: 'Callback fired when the value of the search text input changes.', }, { name: 'validators', type: 'object', description: 'Set rules for the input field to be valid', }, { name: 'isDisabled', type: 'boolean', description: 'Flag to enable/disable the select list. If true, the select list will be disabled', }, { name: 'inputLeftElement', type: 'ReactNode', description: 'Add element to left of inside select input', }, { name: 'inputRightElement', type: 'ReactNode', description: 'Add element to right of inside select input', }, { name: 'inputLeftElementDescription', type: 'string', description: 'Screen reader description for the left input element', }, { name: 'inputRightElementDescription', type: 'string', description: 'Screen reader description for the right input element', }, { name: 'isSearchable', type: 'boolean', description: 'Flag to enable/disable the select list search/filter feature', }, { name: 'options', type: 'object[]', description: 'List of options selectable in the select list input. { label: string, value: string }', }, { name: 'fuseConfig', type: 'shape', description: 'Configs for Fuse', }, { name: 'value', type: 'string', description: 'Option value or list of option values selected in the select list input.', }, { name: 'width', type: 'string', description: 'Width of the select list', }, { name: 'isLoading', type: 'boolean', description: 'Flag to enable/disable the loading state of the select list.', }, { name: 'labelKey', type: 'string', description: 'Set the key value of the label in the options list. Defaults to "label"', }, { name: 'valueKey', type: 'string', description: 'Set the key value of the value in the options list. Defaults to "value"', }, { name: 'maxListHeight', type: 'string | number', description: 'Sets the max height of the dropdown menu', }, { name: 'selectAll', type: 'boolean', description: 'Flag to enable the Select All option', }, { name: 'enableOutsideScroll', type: 'boolean', default: 'false', description: 'Flag to enable scroll on all outside elements', }, { name: 'debounceTime', type: 'number', description: 'Set the length of time that the search should debounce by (in milliseconds)', }, { name: 'apiFiltering', type: 'function', description: 'Api Filter used for fetching search results from an api', }, { name: 'customRender', type: 'function', description: 'Custom render for option items', }, { name: 'virtual', type: 'object | boolean', description: 'Adds virtualization to option item drop-down list', }, { name: 'hideChips', type: 'boolean', description: 'Hide chips and show selected options in comma separated values', }, { name: 'keys', type: 'array[string]', description: 'Keys used by Fuse', default: "['value', 'label']", }, { name: 'retainSectionHeader', type: 'boolean', description: 'Flag to retain the section headers in the results when searching', }, { name: 'highlighted', type: 'boolean', description: 'Flag to enable the background color of select input', }, { name: 'onOpenChange', type: 'function', description: 'Callback fired when the dropdown menu opens or closes. Receives a boolean indicating the open/closed state.', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={SelectInputMulti} rows={[ { name: 'select-input-multi-root', description: 'Root element', }, { name: 'select-input-multi-label', description: 'Label', }, { name: 'select-input-multi-input-container', description: 'Input and option list container', }, { name: 'select-input-multi-input', description: 'Input', }, { name: 'select-input-multi-left-element-wrapper', description: 'Wrapper for left input element', }, { name: 'select-input-multi-left-element', description: 'Input left element', }, { name: 'select-input-multi-right-element-wrapper', description: 'Wrapper for right input element', }, { name: 'select-input-multi-right-element', description: 'Input right element', }, { name: 'select-input-multi-loading-container', description: 'Loading spinner container', }, { name: 'select-input-multi-loading-spinner', description: 'Loading spinner', }, { name: 'select-input-multi-icon-container', description: 'Chevron icon container', }, { name: 'select-input-multi-icon', description: 'Chevron icon', }, { name: 'select-input-multi-descriptors', description: 'Descriptor', }, { name: 'select-input-multi-option-list-container', description: 'Option list container', }, { name: 'select-input-multi-search-container', description: 'Option list search input container', }, { name: 'select-input-multi-search-input', description: 'Option list search input', }, { name: 'select-input-multi-option-list-virtual-container', description: 'Option list container when using virtualization', }, { name: 'select-input-multi-option-list', description: 'Option list', }, { name: 'select-input-multi-no-options', description: 'No options list item', }, { name: 'select-input-multi-option', description: 'Option list item', }, { name: 'select-input-multi-section', description: 'Option list item section', }, { name: 'select-input-multi-option-label', description: 'Option list item label', }, { name: 'select-input-multi-option-checkbox', description: 'Option list item checkbox', }, { name: 'select-input-multi-chip-group', description: 'Chip container', }, { name: 'select-input-multi-chip', description: 'Chip', }, { name: 'select-input-multi-chip-extra-count', description: 'Truncated chip counter', }, { name: 'select-input-multi-no-options-selected', description: 'No Options Selected', }, { name: 'select-input-multi-hide-pills-content', description: 'Hide Pills', }, { name: 'select-input-multi-portal-container', description: 'Portal container', }, ]} /> ``` </Tab> <Tab label="Accessibility"> A combobox is a widget made up of the combination of two distinct elements: - A single-line textbox - An associated pop-up element for helping users set the value of the textbox. The popup may be a listbox, grid, tree, or dialog. Many implementations also include a third optional element -- a graphical button adjacent to the textbox, indicating the availability of the popup. Activating the button displays the popup if suggestions are available. SelectInputMulti adheres to the <ExitLink href="https://www.w3.org/TR/wai-aria-practices-1.2/#combobox">Combobox WAI-ARIA design pattern</ExitLink>. However, SelectInputMulti is not a standard combobox. - It is a merger of a list of selected chips (which can be cleared), and a combobox that allows selection. - We've moved the textbox into the pop-up menu above the listbox, and placed the chips where the textbox typically resides. - It is a multi-selection combobox - which lacks a specific WAI-ARIA example. - The most similar "single-select" combobox example (of the 5 provided) seems to be the <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-list/">Editable Combobox With List Autocomplete Example</ExitLink>. Thus, there is no fully defined WAI-ARIA pattern for SelectInputMulti. SelectInputMulti follows the WAI-ARIA combobox standard for all keystrokes, except for the Enter key, which toggles the checkboxes in the list. ```jsx live () => { const form = useForm(); const { errors, isSubmitted, isSubmitSuccessful } = form.formState; const getIconProps = useCallback( (model) => { if (!isSubmitted) return {}; let iconProps = {}; if (!!errors[model]) { iconProps = { icon: 'error', color: '$error1', size: '18px' }; } if (isSubmitSuccessful) { iconProps = { icon: 'check', color: '$success1', size: '18px' }; } const isEmpty = Object.keys(iconProps).length === 0; return !isEmpty ? { inputRightElement: <IconMaterial {...iconProps} /> } : {}; }, [isSubmitted, isSubmitSuccessful] ); const options = [ { label: 'Vanilla', value: '1' }, { label: 'Chocolate', value: '2' }, { label: 'Strawberry', value: '3' }, { label: 'Cookie Dough', value: '4' }, { label: 'Rocky Road', value: '5' }, ]; return ( <FormProvider state={form}> <SelectInputMulti label="Ice cream flavors" subText="Must pick at least one" searchPlaceholder="Search our flavors..." descriptorsDisplay="column" model="required" isSearchable options={options} {...getIconProps('required')} validators={{ required: 'Pick at least one flavor' }} /> <SelectInputMulti label="Ice cream flavors" model="custom-required" subText="Must pick at least one (with no search or custom messages)" options={options} descriptorsDisplay="column" validators={{ required: true }} /> <SelectInputMulti label="Ice cream flavors" model="validate" descriptorsDisplay="column" subText="Must pick at least one, but no more than two flavors" isSearchable searchPlaceholder="Search our flavors..." options={options} validators={{ required: 'Pick at least one flavor', validate: { noMoreThanTwoAllowed: (v) => { return v.length > 2 ? 'Select a maximum of two flavors' : true; }, }, }} /> <Button type="submit" style={{ marginTop: 15 }}> Submit </Button> </FormProvider> ); }; ``` ```jsx render <Docs.AccessibilityTable title="Textbox" rows={[ { name: 'Down Arrow', description: 'Moves visual focus to the first value in the listbox', }, { name: 'Up Arrow', description: 'Moves visual focus to the last value in the listbox.', }, { name: 'Esc', description: 'Closes the menu.', }, { name: 'Home', description: 'Places the editing cursor at the beginning of the field.', }, { name: 'End', description: 'Places the editing cursor at the end of the field.', }, ]} /> ``` ```jsx render <Docs.AccessibilityTable title="Listbox (if isSearchable)" rows={[ { name: 'Enter', description: 'Toggles the currently highlighted checkbox.', }, { name: 'Esc', description: 'Closes the menu.', }, { name: 'Down Arrow', description: 'Moves visual focus to the next option. If focus is on the last option, moves focus to the first option.', }, { name: 'Up Arrow', description: 'Moves visual focus to the previous option. If focus is on the first option, moves focus to the last option.', }, { name: 'Right Arrow', description: 'Moves focus to the textbox and moves the editing cursor one character to the right.', }, { name: 'Left Arrow', description: 'Moves focus to the textbox and moves the editing cursor one character to the left.', }, { name: 'Home', description: 'Moves focus to the textbox and places the editing cursor at the beginning of the field.', }, { name: 'End', description: 'Moves focus to the textbox and places the editing cursor at the end of the field.', }, ]} /> ``` ```jsx render <Docs.AccessibilityTable title="Listbox" rows={[ { name: 'Enter', description: 'Toggles the currently highlighted checkbox.', }, { name: 'Esc', description: 'Closes the menu.', }, { name: 'Down Arrow', description: 'Moves visual focus to the next option.', }, { name: 'Up Arrow', description: 'Moves visual focus to the previous option.', }, { name: 'Home', description: 'Moves visual focus to the first option.', }, { name: 'End', description: 'Moves visual focus to the last option.', }, ]} /> ``` <h4>Known BrAT (Screen Reader) Issues</h4> - VoiceOver (MacOS) does not correctly announce combobox/listbox status - When expanded, combobox operation does not announce listbox selection or status - These issues match those in WAI-ARIA <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-none/">Editable Combobox without Autocomplete Example</ExitLink> - Un-searchable variant - Unlike searchable variant, NVDA does not announce "not selected" when options receive keyboard focus - JAWS correctly announced "not selected" for both variants </Tab> --- id: service-sandbox category: Data Display title: ServiceSandbox description: Provides a sandbox to test service endpoints. --- <Tab label="Overview"> ```jsx import { ServiceSandbox } from '@uhg-abyss/web/ui/ServiceSandbox'; ``` ```jsx render <Docs.V2Deprecated componentName="ServiceSandbox"></Docs.V2Deprecated> ``` ## JSON response ```jsx live () => { const onSend = (url, options, callback) => { console.log('url', url); console.log('options', options); console.log('callback return response', callback); }; return ( <ServiceSandbox url="http://localhost:8080/Claims/api/claim/action/v1.0" method="get" parameters={[ { in: 'query', key: 'transactionId', description: 'transactionId', type: 'string', }, { in: 'query', key: 'tin', description: 'tin', type: 'string', }, { in: 'header', key: 'Authorization', description: 'Bearer token', type: 'string', }, { in: 'header', key: 'env', description: 'Environment', type: 'string', }, ]} responses={[ { response: '200', description: 'OK', parameters: { query: { transactionId: '12345-123391-129910-1192010', tin: '12345678', }, header: { Authorization: 'Bearer MRLATzo9a4CWw6TaGFFTVX3cY66Ll1OD', env: 'sandbox', }, }, }, { response: '400', description: 'Error', parameters: { query: { transactionId: '00000', tin: '12345678', }, header: { Authorization: 'Bearer MRLATzo9a4CWw6TaGFFTVX3cY66Ll1OD', env: 'sandbox', }, }, }, ]} /> ); }; ``` ## Image response ```jsx live () => { const onSend = (url, options, callback) => { console.log('url', url); console.log('options', options); console.log('callback return response', callback); }; return ( <ServiceSandbox url="http://localhost:8080/Eligibility/api/extended/memberIdCardV2/image" method="get" parameters={[ { in: 'query', key: 'transactionId', description: 'transactionId', type: 'string', }, { in: 'header', key: 'Authorization', description: 'Bearer token', type: 'string', }, ]} responses={[ { response: '200', description: 'OK', parameters: { query: { transactionId: '12345678-567899', }, header: { Authorization: 'Bearer MRLATzo9a4CWw6TaGFFTVX3cY66Ll1OD', env: 'sandbox', }, }, }, { response: '400', description: 'Error', parameters: { query: { transactionId: '000000', }, header: { Authorization: 'Bearer MRLATzo9a4CWw6TaGFFTVX3cY66Ll1OD', env: 'sandbox', }, }, }, ]} /> ); }; ``` ## PDF response ```jsx live () => { const onSend = (url, options, callback) => { console.log('url', url); console.log('options', options); console.log('callback return response', callback); }; return ( <ServiceSandbox url="http://localhost:8080/Claims/api/attachment/v1.0" method="get" parameters={[ { in: 'query', key: 'attachmentId', description: 'attachmentId', type: 'string', }, { in: 'query', key: 'tin', description: 'tin', type: 'string', }, { in: 'header', key: 'Authorization', description: 'Bearer token', type: 'string', }, ]} responses={[ { response: '200', description: 'OK', parameters: { query: { attachmentId: '12345678-12345-489e-8739-f6db8149f5c4%7Cu_prov_attch_2021-01', tin: '12345678', }, header: { Authorization: 'Bearer MRLATzo9a4CWw6TaGFFTVX3cY66Ll1OD', env: 'sandbox', }, }, }, { response: '400', description: 'Error', parameters: { query: { attachmentId: '000000', tin: '12345678', }, header: { Authorization: 'Bearer MRLATzo9a4CWw6TaGFFTVX3cY66Ll1OD', env: 'sandbox', }, }, }, ]} /> ); }; ``` ## File upload ```jsx live () => { const onSend = (url, options, callback) => { console.log('url', url); console.log('options', options); console.log('callback return response', callback); }; return ( <ServiceSandbox url="http://localhost:8080/priorAuth/v1.0/attachment/upload/v1.0" method="post" parameters={[ { in: 'header', key: 'tin', required: true, description: 'tin', type: 'string', }, { in: 'header', key: 'client_id', required: true, description: 'Client ID', type: 'string', }, { in: 'formData', key: 'files', description: 'file', required: true, type: 'file', }, { in: 'formData', key: 'attachmentsRequest', description: 'attachmentsRequest', type: 'string', }, ]} responses={[ { response: '200', description: 'OK', parameters: { header: { tin: '12345678', client_id: '9999999', }, formData: { attachmentsRequest: 'metadata', }, }, }, { response: '400', description: 'Error', parameters: { header: { tin: '0000000', client_id: '0000000', }, formData: { attachmentsRequest: 'metadata', }, }, }, ]} /> ); }; ``` </Tab> --- id: skeleton-v2 category: Overlay title: V2Skeleton description: Placeholder for loading content. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=10574-6415 subDirectory: Skeleton/v2 sourceIsTS: true --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="Skeleton"></Docs.V2MigrationBanner> ``` ```jsx import { V2Skeleton } from '@uhg-abyss/web/ui/Skeleton'; ``` ```jsx sandbox { component: 'V2Skeleton', inputs: [ { prop: 'variant', type: 'select', options: [ { label: 'default', value: 'default' }, { label: 'alternate', value: 'alternate' }, ], }, { prop: 'height', type: 'string', }, { prop: 'width', type: 'string', }, { prop: 'animated', type: 'boolean' }, ], } <V2Skeleton height={100} width={100}></V2Skeleton> ``` ## Usage `V2Skeleton` is a placeholder component for content that is loading. `V2Skeleton` can help convey to users that content is on its way and the page is functioning as intended. ```jsx live () => { const avatar = utils.useBaseUrl('img/team/scott-houser.jpg'); const cardImage = utils.useBaseUrl('img/graphics/card-image-example.png'); const { isOpen: isDoneLoading, onToggle } = useToggle(); const returnContent = () => { if (isDoneLoading) { return ( <React.Fragment> <Announce>profile has loaded</Announce> <Layout.Stack alignItems="left"> <Layout.Group> <Layout.Group> <Box height="50px" width="50px" padding="0px" css={{ 'abyss-box-root': { backgroundImage: `url(${avatar})`, backgroundRepeat: 'no-repeat', backgroundSize: 'cover', borderRadius: '90px', }, }} /> </Layout.Group> <Layout.Group> <Layout.Stack space={0} alignItems="left"> <Text fontWeight={600}>Name goes here</Text> <Text size={'$sm'}>Description</Text> </Layout.Stack> </Layout.Group> </Layout.Group> <Layout.Group> <Box height="100px" width="260px" padding="0px" css={{ 'abyss-box-root': { backgroundImage: `url(${cardImage})`, backgroundRepeat: 'no-repeat', backgroundSize: 'cover', borderRadius: '10px', }, }} /> </Layout.Group> </Layout.Stack> </React.Fragment> ); } return null; }; const returnSkeletonStack = () => { if (!isDoneLoading) { return ( <Layout.Stack alignItems="left"> <Layout.Group> <V2Skeleton width={50} height={50} /> <Layout.Stack> <V2Skeleton width={200} height={20} /> <V2Skeleton width={200} height={20} /> </Layout.Stack> </Layout.Group> <V2Skeleton width={260} height={100} /> </Layout.Stack> ); } return null; }; return ( <Layout.Stack alignItems="left"> {returnContent()} {returnSkeletonStack()} <V2Button style={{ marginTop: '15px' }} onClick={onToggle}> Toggle Loading </V2Button> </Layout.Stack> ); }; ``` ## Width and height Use the `width` and `height` props to size the `V2Skeleton`. The default settings are `100%` for both width and height so if no values are provided, the skeleton will fill the parent container. ```jsx live () => { return ( <Layout.Stack alignItems="left"> <div style={{ width: '100px', height: '100px' }}> <V2Skeleton /> </div> <V2Skeleton width={200} height={50} /> </Layout.Stack> ); }; ``` ## Variant Use the `variant` prop to control the color of the `V2Skeleton` component. The default is `'default'` which displays with a transparent black color. The variant `'alternate'` is displayed with a transparent white, intended for dark backgrounds. ```jsx live () => { return ( <Layout.Stack alignItems="left"> <Box color="white"> <V2Skeleton variant="default" width={200} height={50} /> </Box> <Box color="$gray8"> <V2Skeleton variant="alternate" width={200} height={50} /> </Box> </Layout.Stack> ); }; ``` ## Animated Animation is enabled by default. If you'd like to disable animation pass in the `animated` prop and set to a value of `false`. ```jsx live () => { return ( <Layout.Stack alignItems="left"> <V2Skeleton animated={false} width={200} height={50} /> </Layout.Stack> ); }; ``` ## Loading text Use the `loadingText` prop to specify the offscreen text to be read by the screen reader during loading. Default is `'Loading'`. Note: When using more than one skeleton loader on a page, it's recommended that only one of the skeleton loaders supply the offscreen loading text. You can pass in an empty string, `""`, to prevent any offscreen text from being generated and read by the screen reader. ```jsx live () => { return ( <Layout.Stack alignItems="left"> <V2Skeleton width={200} height={50} loadingText="Loading page content" /> </Layout.Stack> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2Skeleton" propTypeName="V2SkeletonProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2ClassesTable title="V2Skeleton" classes={[SkeletonClassesMetadata]} /> ``` </Tab> <Tab label = "Accessibility"> <h2>Reduced motion</h2> Animations and transitions that have been changed when a user has `prefers-reduced-motion` set to `reduced`: - `animated` no longer applies even when set to `true` <h2>Loading announcement</h2> When there is more than one skeleton element, use `loadingText=""` to eliminate redundant announcements for screen reader users. ```jsx live () => { const avatar = utils.useBaseUrl('img/team/scott-houser.jpg'); const cardImage = utils.useBaseUrl('img/graphics/card-image-example.png'); const { isOpen: isDoneLoading, onToggle } = useToggle(); const returnContent = () => { if (isDoneLoading) { return ( <React.Fragment> <Announce>profile has loaded</Announce> <Layout.Stack alignItems="left"> <Layout.Group> <Layout.Group> <Box height="50px" width="50px" padding="0px" css={{ 'abyss-box-root': { backgroundImage: `url(${avatar})`, backgroundRepeat: 'no-repeat', backgroundSize: 'cover', borderRadius: '90px', }, }} /> </Layout.Group> <Layout.Group> <Layout.Stack space={0} alignItems="left"> <Text fontWeight={600}>Name goes here</Text> <Text size={'$sm'}>Description</Text> </Layout.Stack> </Layout.Group> </Layout.Group> <Layout.Group> <Box height="100px" width="260px" padding="0px" css={{ 'abyss-box-root': { backgroundImage: `url(${cardImage})`, backgroundRepeat: 'no-repeat', backgroundSize: 'cover', borderRadius: '10px', }, }} /> </Layout.Group> </Layout.Stack> </React.Fragment> ); } return null; }; const returnSkeletonStack = () => { if (!isDoneLoading) { return ( <Layout.Stack alignItems="left"> <Layout.Group> <V2Skeleton width={50} height={50} loadingText="" /> <Layout.Stack> <V2Skeleton width={200} height={20} loadingText="" /> <V2Skeleton width={200} height={20} loadingText="" /> </Layout.Stack> </Layout.Group> <V2Skeleton width={260} height={100} loadingText="Loading stuff..." /> </Layout.Stack> ); } return null; }; return ( <Layout.Stack alignItems="left"> {returnContent()} {returnSkeletonStack()} <V2Button style={{ marginTop: '15px' }} onClick={onToggle}> Toggle Loading </V2Button> </Layout.Stack> ); }; ``` </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={V2Skeleton} keys={['skeletonV2']} /> ``` </Tab> --- id: skeleton category: Overlay title: Skeleton description: Placeholder for loading content. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=27600-98953 subDirectory: Skeleton/v1 --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="Skeleton"></Docs.V2MigrationBanner> ``` ```jsx import { Skeleton } from '@uhg-abyss/web/ui/Skeleton'; ``` ```jsx sandbox { component: 'Skeleton', inputs: [ { prop: 'variant', type: 'select', options: [ { label: 'rectangular', value: 'rectangular' }, { label: 'rounded', value: 'rounded' }, { label: 'circular', value: 'circular' }, ], }, { prop: 'height', type: 'string', }, { prop: 'width', type: 'string', }, { prop: 'animated', type: 'boolean' }, ], } <Skeleton height={100} width={100}></Skeleton> ``` ## Usage `Skeleton` is a placeholder component for content that is loading. `Skeleton` can help convey to users that content is on its way and the page is functioning as intended ```jsx live () => { const avatar = utils.useBaseUrl('img/team/scott-houser.jpg'); const cardImage = utils.useBaseUrl('img/graphics/card-image-example.png'); const { isOpen: isDoneLoading, onToggle } = useToggle(); const returnContent = () => { if (isDoneLoading) { return ( <React.Fragment> <Announce>profile has loaded</Announce> <Layout.Stack alignItems="left"> <Layout.Group> <Layout.Group> <Box height="50px" width="50px" padding="0px" css={{ 'abyss-box-root': { backgroundImage: `url(${avatar})`, backgroundRepeat: 'no-repeat', backgroundSize: 'cover', borderRadius: '90px', }, }} /> </Layout.Group> <Layout.Group> <Layout.Stack space={0} alignItems="left"> <Text fontWeight={600}>Name goes here</Text> <Text size={'$sm'}>Description</Text> </Layout.Stack> </Layout.Group> </Layout.Group> <Layout.Group> <Box height="100px" width="260px" padding="0px" css={{ 'abyss-box-root': { backgroundImage: `url(${cardImage})`, backgroundRepeat: 'no-repeat', backgroundSize: 'cover', borderRadius: '10px', }, }} /> </Layout.Group> </Layout.Stack> </React.Fragment> ); } return null; }; const returnSkeletonStack = () => { if (!isDoneLoading) { return ( <Layout.Stack alignItems="left"> <Layout.Group> <Skeleton variant="circular" width={50} height={50} /> <Layout.Stack> <Skeleton variant="rounded" width={200} height={20} /> <Skeleton variant="rounded" width={200} height={20} /> </Layout.Stack> </Layout.Group> <Skeleton variant="rounded" width={260} height={100} /> </Layout.Stack> ); } return null; }; return ( <Layout.Stack alignItems="left"> {returnContent()} {returnSkeletonStack()} <Button style={{ marginTop: '15px' }} onClick={onToggle}> Toggle Loading </Button> </Layout.Stack> ); }; ``` ## Width and height Use the `width` and `height` props to size the Skeleton. The default settings are `100%` for both width and height so if no values are provided the Skeleton will fill the parent container. ```jsx live () => { return ( <Layout.Stack alignItems="left"> <div style={{ width: '100px', height: '100px' }}> <Skeleton /> </div> <Skeleton width={200} height={50} /> </Layout.Stack> ); }; ``` ## Variant Use the `variant` prop to control the shape of the `Skeleton` component. Default is `rectangular` which displays with no rounded edges. `rounded` is displayed with rounded edges and a border radius of `8px`. `circular` is displayed with fully rounded edges. ```jsx live () => { return ( <Layout.Stack alignItems="left"> <Skeleton variant="rectangular" width={200} height={50} /> <Skeleton variant="rounded" width={200} height={50} /> <Skeleton variant="circular" width={50} height={50} /> </Layout.Stack> ); }; ``` ## Animated Animation is enabled by default. If you'd like to disable animation pass in the `animated` prop and set to a value of `false`. ```jsx live () => { return ( <Layout.Stack alignItems="left"> <Skeleton animated={false} variant="rounded" width={200} height={50} /> </Layout.Stack> ); }; ``` ## LoadingText Use the `loadingText` prop to specify the offscreen text to be read by the screen reader during loading. Default is "Loading". Note: When using more than one Skeleton loader on a page, it's recommended that only one of the Skeleton loaders supply the offscreen loading text. You can pass in an empty string, `""`, to prevent any offscreen text from being generated and read by the screen reader. ```jsx live () => { return ( <Layout.Stack alignItems="left"> <Skeleton variant="rounded" width={200} height={50} loadingText="Loading page content" /> </Layout.Stack> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={Skeleton} rows={[ { name: 'width', type: 'number | string', description: 'Set width of skeleton', }, { name: 'height', type: 'number | string', description: 'Set height of skeleton', }, { name: 'animated', type: 'boolean', description: 'Set to false to disable animation.', }, { name: 'variant', type: "'rectangular' | 'rounded' | 'circular'", description: 'Change shape of the skeleton', }, { name: 'loadingText', type: 'string', description: 'Specifies the offscreen text to be read by screen readers as the loading announcement', default: 'Loading', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Skeleton} rows={[ { name: 'skeleton-root', description: 'Root element', }, ]} /> ``` </Tab> <Tab label = "Accessibility"> <h2>Loading Announcement</h2> When there is more than one Skeleton element, use `loadingText=""` to eliminate redundant announcements for screen reader users. ```jsx live () => { const avatar = utils.useBaseUrl('img/team/scott-houser.jpg'); const cardImage = utils.useBaseUrl('img/graphics/card-image-example.png'); const { isOpen: isDoneLoading, onToggle } = useToggle(); const returnContent = () => { if (isDoneLoading) { return ( <React.Fragment> <Announce>profile has loaded</Announce> <Layout.Stack alignItems="left"> <Layout.Group> <Layout.Group> <Box height="50px" width="50px" padding="0px" css={{ 'abyss-box-root': { backgroundImage: `url(${avatar})`, backgroundRepeat: 'no-repeat', backgroundSize: 'cover', borderRadius: '90px', }, }} /> </Layout.Group> <Layout.Group> <Layout.Stack space={0} alignItems="left"> <Text fontWeight={600}>Name goes here</Text> <Text size={'$sm'}>Description</Text> </Layout.Stack> </Layout.Group> </Layout.Group> <Layout.Group> <Box height="100px" width="260px" padding="0px" css={{ 'abyss-box-root': { backgroundImage: `url(${cardImage})`, backgroundRepeat: 'no-repeat', backgroundSize: 'cover', borderRadius: '10px', }, }} /> </Layout.Group> </Layout.Stack> </React.Fragment> ); } return null; }; const returnSkeletonStack = () => { if (!isDoneLoading) { return ( <Layout.Stack alignItems="left"> <Layout.Group> <Skeleton variant="circular" width={50} height={50} loadingText="" /> <Layout.Stack> <Skeleton variant="rounded" width={200} height={20} loadingText="" /> <Skeleton variant="rounded" width={200} height={20} loadingText="" /> </Layout.Stack> </Layout.Group> <Skeleton variant="rounded" width={260} height={100} loadingText="Loading stuff..." /> </Layout.Stack> ); } return null; }; return ( <Layout.Stack alignItems="left"> {returnContent()} {returnSkeletonStack()} <Button style={{ marginTop: '15px' }} onClick={onToggle}> Toggle Loading </Button> </Layout.Stack> ); }; ``` </Tab> --- id: slider-v2 category: Forms title: V2Slider description: Used to traverse through different values in a given range. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=11851-2579 subDirectory: Slider/v2 sourceIsTS: true --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="Slider"></Docs.V2MigrationBanner> ``` ```jsx import { V2Slider } from '@uhg-abyss/web/ui/Slider'; ``` ```jsx sandbox { component: 'V2Slider', inputs: [ { prop: 'label', type: 'string', }, { prop: 'subText', type: 'string', }, { prop: 'minValue', type: 'number', }, { prop: 'maxValue', type: 'number', }, { prop: 'step', type: 'number', }, { prop: 'isDisabled', type: 'boolean', }, ], } () => { const [value, setValue] = React.useState(0); return ( <V2Slider step={10} label="Sandbox Slider" value={value} onChange={(e) => setValue(e)} /> ); }; ``` ## useForm (recommended) Using the `useForm` hook lets the DOM handle form data. ```jsx live () => { const form = useFormV2({ defaultValues: { slider: 10, }, }); return ( <V2FormProvider state={form}> <V2Slider label="useForm Slider" model="slider" step={10} /> </V2FormProvider> ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [value, setValue] = React.useState(0); return ( <V2Slider step={10} label="useState Slider" value={value} onChange={(e) => setValue(e)} /> ); }; ``` ## Label area Use the `label` prop to display the required label above the slider. Props `subText` and `helper` are optional to further customize the label area of the slider. Prop `subText` be used to provide hint text below the `label` of the slider. Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip-v2) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip-v2) or a [Popover](/web/ui/popover-v2). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. Additionally, the `isRequired` prop can be used to add an asterisk next to the label. Since the slider will always have a value, defaulting to the minimum, there is no validation necessary. Therefore, `isRequired` can be used whether using `useForm` or `useState`, which is different behavior than other form components. ```jsx live () => { const form = useFormV2(); return ( <V2FormProvider state={form}> <V2Slider label="Label area" model="slider-label" subText="Subtext goes here" helper="Additional context goes here" step={10} isRequired /> </V2FormProvider> ); }; ``` ## Min & max values Use the `minValue` and `maxValue` properties to set the minimum and maximum values the slider can equal. By default, the range is set to 0 and 100. ```jsx live () => { const form = useFormV2(); return ( <V2FormProvider state={form}> <V2Slider label="Min and max values" model="slider-label" minValue={1} maxValue={5} /> </V2FormProvider> ); }; ``` ## Step To make a discrete slider, the input snaps to specific values, decided by the `step` prop. Use the `step` property to set the number that the value will increment/decrement on change. Default is `1`. ```jsx live () => { const form = useFormV2(); return ( <V2FormProvider state={form}> <V2Slider label="Step of 5" model="slider-label" minValue={0} maxValue={20} step={5} /> </V2FormProvider> ); }; ``` ## Marks config The `V2Slider` marks can be customized with `marksConfig`. The type is as follows: ```ts { showMarks?: 'none' | 'endpoints' | 'step'; marks?: Array<{ value: number; label: string }>; customLabel?: (value: number) => string; } ``` `showMarks` can be set to `none`, `endpoints`, or `step`. If set to `endpoints`, marks will only be shown at the minimum and maximum values. If set to `step` (the default), marks will be shown at every step. If set to `none`, no marks will be shown. `marks` can be used to provide custom marks at specific values, which is useful if you do not want any of the `showMarks` options. Each mark should be an object with a `value` and a `label`. ```jsx live () => { const form = useFormV2(); const marksConfig = { showMarks: 'endpoints', customLabel: (value) => `$${value}`, }; return ( <V2FormProvider state={form}> <V2Slider label="Custom Marks" subText="Marks can be customized or display custom labels" model="slider" prefix="$" minValue={5} maxValue={35} marksConfig={marksConfig} /> </V2FormProvider> ); }; ``` ```jsx live () => { const form = useFormV2(); const marksConfig = { marks: [ { value: 5, label: '$5' }, { value: 15, label: '$15' }, { value: 25, label: '$25' }, { value: 35, label: '$35' }, ], }; return ( <V2FormProvider state={form}> <V2Slider label="Custom Marks" subText="Marks can be customized or display custom labels" model="slider" prefix="$" marksConfig={marksConfig} minValue={5} maxValue={35} /> </V2FormProvider> ); }; ``` ## Track tooltip config The track tooltip can be customized with `tooltipConfig`. The type is as follows: ```ts { alwaysOn?: boolean; showOnHover?: boolean; customLabel?: (value: number) => string; } ``` Use `alwaysOn` to keep the popover always displayed. `showOnHover` can be used to display the tooltip when the user hovers over the thumb. Use `customLabel` to set a custom label for the tooltip. ```jsx live () => { const form = useFormV2(); const tooltipConfig = { alwaysOn: true, showOnHover: true, customLabel: (value) => `${value}lbs`, }; const marksConfig = { showMarks: 'none', }; return ( <V2FormProvider state={form}> <V2Slider label="Custom tooltip" model="slider" suffix="lbs" step={10} tooltipConfig={tooltipConfig} marksConfig={marksConfig} /> </V2FormProvider> ); }; ``` ## Disabled Use the `isDisabled` property to disable the slider. ```jsx live () => { const form = useFormV2({ defaultValues: { slider: 10, }, }); return ( <V2FormProvider state={form}> <V2Slider label="useForm Slider" model="slider" step={10} isDisabled /> </V2FormProvider> ); }; ``` ## Form input customization Similar to [V2TextInput](/web/ui/text-input-v2), the `V2Slider` form input can be customized by providing a `prefix` or `suffix`. Note that not all props for `V2TextInput` are applicable to `V2Slider`. ```jsx live () => { const form = useFormV2(); const onSubmit = (data) => { console.log('Form submitted:', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2Slider label="Custom form input" model="slider" prefix="$" suffix="USD" step={10} /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2Slider" propTypeName="V2SliderProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2ClassesTable title="V2Slider" classes={[SliderClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> # Slider V2Slider's design merges a number entry field (HTML `<input type="number">` announced as "spinbox") with an slider. From an accessibility perspective, having dual controls active to update a single value can be redundant, confusing, and unnecessary. - For keyboard users, It adds an extra tab stop in the focus order and duplicate controls for the entering the same value - For screen reader users, the redundant slider following the input box will be unexpected and particularly confusing To simplify and address these issues, `V2Slider`'s keyboard and screen reader interactions are restricted to the number entry field. All slider functionality and information have direct equivalents in then number field. This makes the visible "slider" redundant, so it is not directly accessed or announced. The resulting changes are: - Keyboard experience: Only number/spinbox field receives keyboard focus - Since it is tied to the slider thumb, sighted users will see slider updates and have equivalent control of it - Screen reader experience: The entire slider is hidden from screen readers (using `aria-hidden="true"`) - This suppresses any announcement of the thumb and any index marks - The input field implementation using `<input type="number">` eliminates the ability to use `aria-textvalue` - As result, any prefix or suffix settings to the field are added as part of the field label (using `aria-labelledby`) which aligns as extended field sub-labels. ```jsx live () => { const [value, setValue] = React.useState(50); const tooltipConfig = { alwaysOn: true, customLabel: (value) => `~${value}%`, }; const marksConfig = { customLabel: (value) => `${value}%`, }; return ( <V2Slider label="Abyss satisfaction (approximate)" value={value} onChange={(e) => setValue(e)} prefix="~" suffix="%" subText="Values are 5% increments" helper="Why? Because we want to get 100%" step={5} isRequired tooltipConfig={tooltipConfig} marksConfig={marksConfig} /> ); }; ``` ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Right Arrow:', description: 'Edit the number in the input field.', }, { name: 'Up Arrow:', description: 'Increase the value of the slider form input by one step.', }, { name: 'Down Arrow:', description: 'Decrease the value of the slider form input by one step.', }, { name: 'Left Arrow:', description: 'Edit the number in the input field.', }, { name: 'Home:', description: 'Set the value to the minimum.', }, { name: 'End:', description: 'Set the value to the maximum.', }, ]} /> ``` </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={V2Slider} keys={['sliderV2']} /> ``` </Tab> --- id: slider category: Forms title: Slider description: Used to traverse through different values in a given range. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=25096-98321 subDirectory: Slider/v1 --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="Slider"></Docs.V2MigrationBanner> ``` ```jsx import { Slider } from '@uhg-abyss/web/ui/Slider'; ``` ```jsx sandbox { component: 'Slider', inputs: [ { prop: 'label', type: 'string', }, { prop: 'errorMessage', type: 'string', }, { prop: 'minValue', type: 'number', }, { prop: 'maxValue', type: 'number', }, { prop: 'step', type: 'number', }, { prop: 'hideLabel', type: 'boolean', }, { prop: 'popoverAlwaysOn', type: 'boolean', }, { prop: 'disablePopover', type: 'boolean', }, { prop: 'isDisabled', type: 'boolean', }, { prop: 'showMarks', type: 'boolean', }, ], } () => { const [value, setValue] = React.useState(0); return ( <Slider step={10} label="Sandbox Slider" value={value} onChange={(e) => setValue(e)} /> ); }; ``` ## useForm (recommended) Using the `useForm` hook lets the DOM handle form data. ```jsx live () => { const form = useForm({ defaultValues: { slider: 0, }, }); const handleSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={handleSubmit}> <Slider label="Form Slider" model="slider" validators={{ required: true }} /> <Button type="submit">Submit</Button> </FormProvider> ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [value, setValue] = React.useState(25); return ( <React.Fragment> <Slider label="State Slider" value={value} onChange={(e) => setValue(e)} /> <Button onClick={() => console.log(value)}>Submit</Button> </React.Fragment> ); }; ``` ## Range slider ```jsx live () => { const [value, setValue] = useState([-20, 20]); const form = useForm({ defaultValues: { slider: [-30, 30], }, }); const handleSubmit = (data) => { console.log('data', data); }; return ( <React.Fragment> <FormProvider state={form} onSubmit={handleSubmit}> <Slider label="Range Slider Form" model="slider" step={10} minValue={-50} maxValue={50} minRange={10} showMarks isRange validators={{ required: true }} /> <Button type="submit">Submit</Button> </FormProvider> <Slider label="Range Slider State" value={value} onChange={(e) => setValue(e)} step={10} minValue={-50} maxValue={50} minRange={10} showMarks isRange /> <Button onClick={() => handleSubmit(value)}>Submit</Button> </React.Fragment> ); }; ``` ## Label Use the `label` property to display a label above the slider. To hide the label set `hideLabel` to `true`. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <Slider label="Visible Label" model="slider-label" /> <Slider label="Hidden Label" model="slider-hideLabel" subText="Hidden Label" hideLabel /> </FormProvider> ); }; ``` ## Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip) or a [Popover](/web/ui/popover). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live () => { const form = useForm({ defaultValues: { 'helper-tooltip': 0, 'helper-custom': [-30, 30], }, }); return ( <FormProvider state={form}> <Slider label="Default Helper" helper="This is a tooltip" model="helper-tooltip" /> <Slider label="Custom Helper" helper={ <Popover title="Custom Helper" content="This is a popover with a custom icon" > <IconSymbol icon="help" variant="outlined" color="$success1" size="$sm" /> </Popover> } model="helper-custom" step={10} minValue={-50} maxValue={50} minRange={10} showMarks isRange validators={{ required: true }} /> </FormProvider> ); }; ``` ## Min & max values Use the `minValue` and `maxValue` properties to set the minimum and maximum values the slider can equal. ```jsx live () => { const form = useForm({ defaultValues: { slider: 25, }, }); return ( <FormProvider state={form}> <Slider label="Min/Max Values" model="slider" minValue={-50} maxValue={50} step={25} showMarks /> </FormProvider> ); }; ``` ## Step value Use the `step` property to set the number by which value will be incremented/decremented with thumb drag and arrows. ```jsx live () => { const form = useForm({ defaultValues: { slider: 20, }, }); return ( <FormProvider state={form}> <Slider label="Step Value" model="slider" step={20} showMarks /> </FormProvider> ); }; ``` ## Marks Use the `showMarks` property to display marks which will be placed on the track based on the `step` value. ```jsx live () => { const form = useForm({ defaultValues: { slider: 20, }, }); return ( <FormProvider state={form}> <Slider label="Slider Marks" model="slider" step={10} showMarks /> </FormProvider> ); }; ``` Make marks that display at uneven intervals by passing the `marks` prop. `marks` must be an array of JSON objects containing a `value` and `label` property. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <Slider label="Irregular Marks" marks={[ { value: 0, label: '0%' }, { value: 20, label: '20%' }, { value: 40, label: '40%' }, { value: 80, label: '80%' }, ]} showMarks /> </FormProvider> ); }; ``` ## Custom mark label Use the `customMarkLabel` property to override the default mark label. ```jsx live () => { const form = useForm({ defaultValues: { slider: 20, }, }); return ( <FormProvider state={form}> <Slider label="Custom Mark Label" model="slider" step={10} showMarks customMarkLabel={(e) => `${e}%`} /> </FormProvider> ); }; ``` ## Validation Use the `validators` prop to set rules for the slider value to be valid. ```jsx live () => { const form = useForm({ defaultValues: { slider: 15, }, }); const handleSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={handleSubmit}> <Slider label="Validation" model="slider" validators={{ validate: (value) => value >= 20 || 'Must be larger than 20', }} /> <Button type="submit">Submit</Button> </FormProvider> ); }; ``` ## Disabled Use the `isDisabled` property to disable the slider. ```jsx live () => { const form = useForm({ defaultValues: { slider: 25, sliderRange: [25, 75], }, }); return ( <FormProvider state={form}> <Slider label="Disabled Slider" model="slider" isDisabled /> <Slider label="Disabled Range Slider" model="sliderRange" isDisabled isRange /> </FormProvider> ); }; ``` ## Popover always on Use the `popoverAlwaysOn` property to keep the popover always displayed. ```jsx live () => { const form = useForm({ defaultValues: { slider: 25, }, }); return ( <FormProvider state={form}> <Slider label="Always On Popover" model="slider" popoverAlwaysOn /> </FormProvider> ); }; ``` ## Hide popover Use the `disablePopover` property to hide the popover. ```jsx live () => { const form = useForm({ defaultValues: { slider: 25, }, }); return ( <FormProvider state={form}> <Slider label="Disable Popover" model="slider" disablePopover /> </FormProvider> ); }; ``` ## Custom popover label Use the `customPopoverLabel` property to override the default value displayed in the popover. ```jsx live () => { const form = useForm({ defaultValues: { dollar: 0, percent: 25, temp: 75, }, }); return ( <FormProvider state={form}> <Slider label="Dollar Label" model="dollar" popoverAlwaysOn customPopoverLabel={(value) => { return `$${value}`; }} /> <Slider label="Label Percent" model="percent" popoverAlwaysOn customPopoverLabel={(value) => { return `${value}%`; }} /> <Slider label="Temperature Label" model="temp" popoverAlwaysOn customPopoverLabel={(value) => { return `${value}°F`; }} /> </FormProvider> ); }; ``` ## Custom text values Utilize an array such as `Marks` below to change the slider text displayed from numbers to entire text values. ```jsx live () => { const MARKS = [ { value: 0, label: 'xs' }, { value: 1, label: 'sm' }, { value: 2, label: 'md' }, { value: 3, label: 'lg' }, { value: 4, label: 'xl' }, ]; const form = useForm({ defaultValues: { slider: 0, }, }); return ( <FormProvider state={form}> <Slider label="Custom Text Values" model="slider" customMarkLabel={(val) => MARKS.find((mark) => mark.value === val).label } customPopoverLabel={(val) => MARKS.find((mark) => mark.value === val).label } maxValue={4} showMarks /> </FormProvider> ); }; ``` ## Error message Use the `errorMessage` prop to display a custom error message below the slider. Note: The errorMessage prop does not work with useForm and is only applicable within our form input components when useState is being utilized. See the [useForm Docs](/web/hooks/use-form#set-error) for example use cases with useForm. ```jsx live () => { const [value, setValue] = useState(20); return ( <React.Fragment> <Slider label="Error Message" value={value} onChange={(e) => setValue(e)} errorMessage="Custom Error Message" /> </React.Fragment> ); }; ``` ## Subtext Use the `subText` prop to display helpful text below the slider. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <Slider label="Sub Text" model="slider" subText="Custom SubText" /> </FormProvider> ); }; ``` ## Descriptors display Use the `descriptorsDisplay` prop to set the orientation of the error message and subtext descriptor content. Available variants include 'column' and 'row'. The default is set to 'row'. Use the [FormProvider](/web/ui/form-provider#descriptors-display) and `descriptorsDisplay` to set the descriptors orientation across an entire form. ```jsx live () => { const [value, setValue] = useState(20); return ( <React.Fragment> <Slider value={value} onChange={(e) => setValue(e)} label="Descriptors Display" subText="Subtext Message" errorMessage="Error Message" descriptorsDisplay="column" /> </React.Fragment> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={Slider} rows={[ { name: 'children', type: 'ReactNode', description: 'The contents of the slider component', }, { name: 'customPopoverLabel', type: 'function', description: 'Set custom popover label', }, { name: 'customMarkLabel', type: 'function', description: 'Set custom mark label', }, { name: 'onChange', type: 'function', description: 'Callback fired every time the value changes', }, { name: 'onFocus', type: 'function', description: 'Callback fired every time the component is focused', }, { name: 'onBlur', type: 'function', description: 'Callback fired every time the component is unfocused', }, { name: 'isRange', type: 'boolean', description: 'Flag to set if slider is a range', }, { name: 'hideLabel', type: 'boolean', description: 'Flag to hide label', }, { name: 'minValue', type: 'number', description: 'Set min value', }, { name: 'maxValue', type: 'number', description: 'Set max value', }, { name: 'step', type: 'number', description: 'Set number of steps', }, { name: 'pageUpDownStep', type: 'number', description: 'Set number of steps for page up and page down keyboard shortcuts. Defaults to 10', }, { name: 'minRange', type: 'number', description: 'Set minimum range difference in range slider', }, { name: 'label', type: 'string', description: 'Set label', }, { name: 'helper', type: 'node | string', description: 'Helper element next to field label', }, { name: 'model', type: 'string', description: 'Unique identifier used for FormProvider', }, { name: 'errorMessage', type: 'string', description: 'Set error message', }, { name: 'subText', type: 'string', description: 'Text displayed below the slider', }, { name: 'descriptorsDisplay', type: '"row" | "column"', description: 'Set the orientation of descriptor content located below the slider', }, { name: 'popoverAlwaysOn', type: 'boolean', description: 'Flag to set popover always on', }, { name: 'disablePopover', type: 'boolean', description: 'Flag to disable popover', }, { name: 'isDisabled', type: 'boolean', description: 'Flag to disable slider', }, { name: 'validation', type: 'shape', description: 'Set rules for slider validation', }, { name: 'showMarks', type: 'boolean', description: 'Flag to show slider marks', }, { name: 'marks', type: 'array', description: 'Display custom marks using an array of objects with label and value properties', }, { name: 'thumbLabel', type: 'string', description: 'aria-label override for thumb label', }, { name: 'thumbToLabel', type: 'string', description: 'aria-label override for to/minimum thumb label when using range slider', }, { name: 'thumbFromLabel', type: 'string', description: 'aria-label override for from/maximum thumb label when using range slider', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Slider} rows={[ { name: 'slider-root', description: 'Slider root element', }, { name: 'slider-label', description: 'Label', }, { name: 'slider-input', description: 'Input element', }, { name: 'slider-thumb', description: 'Slider thumb', }, { name: 'slider-thumb-popover', description: 'Slider thumb popover', }, { name: 'slider-thumb-popover-label', description: 'Slider thumb popover label', }, { name: 'slider-track-wrapper', description: 'Track wrapper', }, { name: 'slider-track', description: 'Track', }, { name: 'slider-track-filler', description: 'Track filler', }, { name: 'slider-track-mark-wrapper', description: 'Wrapper for tracks on track', }, { name: 'slider-track-marks', description: 'Marks on track', }, { name: 'slider-track-mark-text', description: 'Text at each mark', }, { name: 'slider-descriptor', description: 'Descriptors for subtext and error messages', }, ]} /> ``` </Tab> <Tab label="Accessibility"> # Slider A slider is an input where the user selects a value from within a given range. Sliders typically have a slider thumb that can be moved along a bar or track to change the value of the slider. Adheres to the <ExitLink href="https://www.w3.org/TR/wai-aria-practices-1.2/#slider">Slider WAI-ARIA design pattern</ExitLink>. ```jsx live () => { const [value, setValue] = React.useState(25); return ( <React.Fragment> <Slider label="State Slider" value={value} onChange={(e) => setValue(e)} /> <Button onClick={() => console.log(value)}>Submit</Button> </React.Fragment> ); }; ``` ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Right Arrow:', description: 'Increase the value of the slider by one step.', }, { name: 'Up Arrow:', description: 'Increase the value of the slider by one step.', }, { name: 'Down Arrow:', description: 'Decrease the value of the slider by one step.', }, { name: 'Left Arrow:', description: 'Decrease the value of the slider by one step.', }, { name: 'Home:', description: 'Set the slider to the first allowed value in its range.', }, { name: 'End:', description: 'Set the slider to the last allowed value in its range.', }, { name: 'Page Up:', description: 'Increase the slider value by an amount larger than the step change made by Up Arrow.', }, { name: 'Page Down:', description: 'Decrease the slider value by an amount larger than the step change made by Down Arrow.', }, ]} /> ``` # Slider (Multi-Thumb) A multi-thumb slider is a slider with two or more thumbs that each set a value in a group of related values. For example, in a product search, a two-thumb slider could be used to enable users to set the minimum and maximum price limits for the search. In many two-thumb sliders, the thumbs are not allowed to pass one another, such as when the slider sets the minimum and maximum values for a range. For example, in a price range selector, the maximum value of the thumb that sets the lower end of the range is limited by the current value of the thumb that sets the upper end of the range. Conversely, the minimum value of the upper end thumb is limited by the current value of the lower end thumb. However, in some multi-thumb sliders, each thumb sets a value that does not depend on the other thumb values. Adheres to the <ExitLink href="https://www.w3.org/TR/wai-aria-practices-1.2/#slidertwothumb">Slider WAI-ARIA design pattern</ExitLink>. ```jsx live () => { const [value, setValue] = useState([-20, 20]); const form = useForm({ defaultValues: { slider: [-30, 30], }, }); const handleSubmit = (data) => { console.log('data', data); }; return ( <React.Fragment> <FormProvider state={form} onSubmit={handleSubmit}> <Slider label="Range Slider Form" model="slider" step={10} minValue={-50} maxValue={50} showMarks isRange /> <Button type="submit">Submit</Button> </FormProvider> <Slider label="Range Slider State" value={value} onChange={(e) => setValue(e)} step={10} minValue={-50} maxValue={50} showMarks isRange /> <Button onClick={() => handleSubmit(value)}>Submit</Button> </React.Fragment> ); }; ``` ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Right Arrow', description: 'Increase the value of the slider by one step.', }, { name: 'Up Arrow', description: 'Increase the value of the slider by one step.', }, { name: 'Left Arrow', description: 'Decrease the value of the slider by one step.', }, { name: 'Home', description: 'Set the slider to the first allowed value in its range.', }, { name: 'End', description: 'Set the slider to the last allowed value in its range.', }, { name: 'Page Up:', description: 'Increase the slider value by an amount larger than the step change made by Up Arrow.', }, { name: 'Page Down:', description: 'Decrease the slider value by an amount larger than the step change made by Down Arrow.', }, ]} /> ``` </Tab> --- id: split-button-v2 category: Content title: V2SplitButton description: Displays a menu triggered by a button, such as a set of actions or functions. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=12319-7189 sourcePath: ui/SplitButton/SplitButton.tsx sourceIsTS: true --- <Tab label="Overview"> ```jsx import { V2SplitButton } from '@uhg-abyss/web/ui/SplitButton'; ``` ## Overview The `V2SplitButton` component is a button that has a main action and a dropdown menu. It is used to display a set of actions or functions that can be triggered by the user. The component is designed to be flexible and customizable, allowing you to define the menu items, their actions, and how they are displayed. The dropdown, known as the Action Menu, can contain single menu items, checkboxes, radio groups, and submenus. Each item can have an icon. ```jsx live () => { const [person, setPerson] = useState('Pedro'); const [urlsChecked, setUrlsChecked] = useState(false); const [foldersChecked, setFoldersChecked] = useState(true); const [bookmarksChecked, setBookmarksChecked] = useState(false); const [termsChecked, setTermsChecked] = useState(false); const actionButtonClick = () => { alert('Primary option selected!'); }; const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, }, { title: 'New Private Window', onClick: () => { console.log('Clicked New Private Window!'); }, disabled: true, }, { title: 'Home', icon: ( <IconSymbol icon="home" variant="outlined" color="$action-menu-v2.color.text.menu-item.default" /> ), onClick: () => { console.log('Clicked Home'); }, }, { title: 'Sub menu', icon: ( <IconSymbol icon="star" variant="outlined" color="$action-menu-v2.color.text.menu-item.default" /> ), subMenu: [ { title: 'Save As...', icon: ( <IconSymbol icon="save" variant="outlined" color="$action-menu-v2.color.text.menu-item.default" /> ), onClick: () => { console.log('Clicked Save As'); }, }, { checkboxes: [ { label: 'Accept Terms', value: 'Accept Terms', checked: termsChecked, onChange: setTermsChecked, }, ], }, ], }, { checkboxes: [ { label: 'Show Bookmarks', value: 'Show Bookmarks', checked: bookmarksChecked, onChange: setBookmarksChecked, }, { label: 'Show Full Urls', value: 'Show Full Urls', checked: urlsChecked, onChange: setUrlsChecked, disabled: true, }, { label: 'Show Folders', value: 'Show Folders', checked: foldersChecked, onChange: setFoldersChecked, }, ], }, { label: 'Radio Group', value: person, onChange: setPerson, radios: [ { label: 'Pedro Pascal', value: 'Pedro', }, { label: 'Tom Cruise', value: 'Tom' }, { label: 'Dwayne Johnson', value: 'Dwayne', disabled: true, }, ], }, ]; return ( <React.Fragment> <V2SplitButton label="Options" menuItems={menuItems} onClick={actionButtonClick} /> </React.Fragment> ); }; ``` ## Label Use the `label` prop to set the text of the main action button. ```jsx live () => { const actionButtonClick = () => { console.log('Primary Action Clicked'); }; const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, }, { title: 'Open New Tab', onClick: () => { console.log('Open New Tab!'); }, }, { title: 'Save As...', onClick: () => { console.log('Save As...'); }, icon: true, }, ]; return ( <Layout.Group> <V2SplitButton label="Options" menuItems={menuItems} onClick={actionButtonClick} /> </Layout.Group> ); }; ``` ## Outline Use the `outline` prop to control the outline of the `SplitButton`. The default is `true`. When setting the prop to `false`, the border radius will be removed and the component will have a flat appearance. Note: An `outline` should be used if the `SplitButton` is used on a background that does not meet the 3:1 color contrast ratio. ```jsx live () => { const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, }, { title: 'Open New Tab', onClick: () => { console.log('Open New Tab!'); }, }, { title: 'Save As...', onClick: () => { console.log('Save As...'); }, icon: true, }, ]; return ( <React.Fragment> <Layout.Group space={20}> <V2SplitButton label="Options" menuItems={menuItems} /> <V2SplitButton label="Options" menuItems={menuItems} outline={false} /> </Layout.Group> </React.Fragment> ); }; ``` ## isDisabled Use the `isDisabled` prop to disable the entire `SplitButton` ```jsx live () => { const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, disabled: false, }, ]; const actionButtonClick = () => { console.log('Primary Action Clicked'); }; return ( <Layout.Group space={20}> <V2SplitButton isDisabled label="Options" menuItems={menuItems} onOutsideClick={(e) => { console.log('Custom Outside Click', e); }} onClick={actionButtonClick} /> </Layout.Group> ); }; ``` ## isLoading Use the `isLoading` prop to place the Action Menu in a loading state. This will display a loading spinner in place of the menu items while the menu is loading. You can also provide the optional prop `loadingLabel` for additional context when the menu is in a loading state. This prop takes the form of an object as explained in our [V2LoadingSpinner](/web/ui/loading-spinner-v2#label) documentation. ```jsx live () => { const [loading, setLoading] = useState(false); const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, }, ]; const actionButtonClick = () => { console.log('Primary Action Clicked'); }; return ( <Layout.Group space={20}> <V2SplitButton isLoading={loading} label="Options" menuItems={menuItems} loadingLabel={{ heading: 'Loading menu', headingLevel: 3, bodyText: 'Please wait...', }} onClick={actionButtonClick} /> <V2Button onClick={() => setLoading(!loading)}>Trigger Loading</V2Button> </Layout.Group> ); }; ``` ## Menu items Use the `menuItems` prop to specify what will be displayed in the Action Menu. The prop requires an array of objects that have the following forms: ### Action item ```ts interface ActionMenuItemProps { title: string; onClick: Function; icon: ReactNode; //optional isSeparated: boolean; //optional disabled: boolean; //optional } ``` ### Checkbox ```ts interface ActionMenuCheckboxItemProps { checkboxes: Array<{ label: string; checked: bool; onChange: func; disabled: bool; //optional }>; } ``` ### Radio group ```ts interface ActionMenuRadioItemProps { label: string; value: string; onChange: Function; radios: Array<{ label: string; value: string; disabled: bool; //optional }>; } ``` ### Submenu ```ts interface ActionMenuItemGroupSubMenuItem { title: string; subMenu: ActionMenuItemGroupItem[]; // any of the above types } ``` ## Inserting icons There are two types of icons that can be added to the `SplitButton`: - Use the `before` prop to insert an icon before the main action button label. - Use the `icon` prop in the menu items to insert icons before to the item title. While this prop accepts any React node, the examples on this page use our [IconSymbol](/web/ui/icon-symbol) component. ```jsx live () => { const actionButtonClick = () => { console.log('Primary Action Clicked'); }; const menuItems = [ { title: 'Home', onClick: () => { console.log('Clicked Home'); }, icon: ( <IconSymbol icon="home" variant="outlined" color="$action-menu-v2.color.text.menu-item.default" /> ), }, { title: 'New Window', onClick: () => { console.log('New Window!'); }, icon: ( <IconSymbol icon="window" variant="outlined" color="$action-menu-v2.color.text.menu-item.default" /> ), }, { title: 'Open New Tab', onClick: () => { console.log('Open New Tab!'); }, icon: ( <IconSymbol icon="tab" variant="outlined" color="$action-menu-v2.color.text.menu-item.default" /> ), }, { title: 'Save As...', onClick: () => { console.log('Save As...'); }, icon: ( <IconSymbol icon="save" variant="outlined" color="$action-menu-v2.color.text.menu-item.default" /> ), }, ]; return ( <V2SplitButton label="Options" menuItems={menuItems} onClick={actionButtonClick} before={ <IconSymbol icon="settings" variant="outlined" size={20} color="$core.color.brand.100" /> } /> ); }; ``` ## onClick There are two types of `onClick` functions you can use with the `SplitButton`: - To provide an action to perform when clicking the main action button, use the `onClick` prop of the `V2SplitButton` component. - To provide an action to perform when clicking a menu item, use the `onClick` prop of the menu item object. ```jsx live () => { const actionButtonClick = () => { console.log('Primary Action Clicked'); }; const menuItems = [ { title: 'New Window', onClick: () => { console.log('New Window!'); }, }, { title: 'Open New Tab', onClick: () => { console.log('Open New Tab!'); }, }, { title: 'Save As...', onClick: () => { console.log('Save As...'); }, icon: ( <IconSymbol icon="save" variant="outlined" color="$action-menu-v2.color.text.menu-item.default" /> ), disabled: true, }, ]; return ( <V2SplitButton label="Options" menuItems={menuItems} onClick={actionButtonClick} /> ); }; ``` ## onChange Use the `onChange` function to trigger a custom function when a checkbox or a radio item is clicked. You can use this to update your checked state, among other things. ```jsx live () => { const [person, setPerson] = useState('Pedro'); const [urlsChecked, setUrlsChecked] = useState(false); const [foldersChecked, setFoldersChecked] = useState(true); const [bookmarksChecked, setBookmarksChecked] = useState(false); const [termsChecked, setTermsChecked] = useState(false); const actionButtonClick = () => { console.log('Primary Action Clicked'); }; const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, }, { title: 'New Private Window', onClick: () => { console.log('Clicked New Private Window!'); }, disabled: true, }, { title: 'Home', icon: ( <IconSymbol icon="home" variant="outlined" color="$action-menu-v2.color.text.menu-item.default" /> ), onClick: () => { console.log('Clicked Home'); }, }, { title: 'Sub menu', icon: ( <IconSymbol icon="star" variant="outlined" color="$action-menu-v2.color.text.menu-item.default" /> ), subMenu: [ { title: 'Save As...', icon: ( <IconSymbol icon="save" variant="outlined" color="$action-menu-v2.color.text.menu-item.default" /> ), onClick: () => { console.log('Clicked Save As'); }, }, { checkboxes: [ { label: 'Accept Terms', value: 'Accept Terms', checked: termsChecked, onChange: setTermsChecked, }, ], }, ], }, { checkboxes: [ { label: 'Show Bookmarks', value: 'Show Bookmarks', checked: bookmarksChecked, onChange: setBookmarksChecked, }, { label: 'Show Full Urls', value: 'Show Full Urls', checked: urlsChecked, onChange: setUrlsChecked, disabled: true, }, { label: 'Show Folders', value: 'Show Folders', checked: foldersChecked, onChange: setFoldersChecked, }, ], }, { label: 'Radio Group', value: person, onChange: setPerson, radios: [ { label: 'Pedro Pascal', value: 'Pedro', }, { label: 'Tom Cruise', value: 'Tom' }, { label: 'Dwayne Johnson', value: 'Dwayne', disabled: true, }, ], }, ]; return ( <V2SplitButton label="Options" menuItems={menuItems} onClick={actionButtonClick} /> ); }; ``` ## Disabled menu items When the `disabled` flag is set to `true` on a menu item, that item cannot be interacted with. This prop applies to all item types, including action items, checkboxes, and radio groups. The item will be visually styled to indicate that it is disabled. ```jsx live () => { const [bookmarksChecked, setBookmarksChecked] = useState(false); const [urlsChecked, setUrlsChecked] = useState(true); const [person, setPerson] = useState('Tom'); const actionButtonClick = () => { console.log('Primary Action Clicked'); }; const menuItems = [ { title: 'New Window', onClick: () => { console.log('New Window!'); }, disabled: true, }, { title: 'New Private Window', onClick: () => { console.log('Clicked New Private Window!'); }, }, { checkboxes: [ { label: 'Show Bookmarks', value: 'Show Bookmarks', checked: bookmarksChecked, onChange: setBookmarksChecked, disabled: true, }, { label: 'Show Full Urls', value: 'Show Full Urls', checked: urlsChecked, onChange: setUrlsChecked, }, ], }, { label: 'Radio Group', value: person, onChange: setPerson, radios: [ { label: 'Pedro Pascal', value: 'Pedro', }, { label: 'Tom Cruise', value: 'Tom' }, { label: 'Dwayne Johnson', value: 'Dwayne', disabled: true, }, ], }, ]; return ( <V2SplitButton label="Options" menuItems={menuItems} onClick={actionButtonClick} /> ); }; ``` ## isSeparated When the `isSeparated` flag is set to `true` on a menu item, a horizontal divider will be inserted after that item. [Checkbox](#checkbox) and [radio group](#radio-group) items automatically render a divider both before and after the item, so no `isSeparated` flag is required. A divider will not be rendered before the first item or after the last item. ```jsx live () => { const [person, setPerson] = useState('Pedro'); const [urlsChecked, setUrlsChecked] = useState(false); const [foldersChecked, setFoldersChecked] = useState(true); const [bookmarksChecked, setBookmarksChecked] = useState(false); const [termsChecked, setTermsChecked] = useState(false); const actionButtonClick = () => { console.log('Primary Action Clicked'); }; const menuItems = [ { title: 'New Window', onClick: () => { console.log('Clicked New Window!'); }, }, { title: 'New Private Window', onClick: () => { console.log('Clicked New Private Window!'); }, disabled: true, isSeparated: true, }, { title: 'Home', icon: ( <IconSymbol icon="home" variant="outlined" color="$action-menu-v2.color.text.menu-item.default" /> ), onClick: () => { console.log('Clicked Home'); }, }, { title: 'Sub menu', icon: ( <IconSymbol icon="star" variant="outlined" color="$action-menu-v2.color.text.menu-item.default" /> ), subMenu: [ { title: 'Save As...', icon: ( <IconSymbol icon="save" variant="outlined" color="$action-menu-v2.color.text.menu-item.default" /> ), onClick: () => { console.log('Clicked Save As'); }, }, { checkboxes: [ { label: 'Accept Terms', value: 'Accept Terms', checked: termsChecked, onChange: setTermsChecked, }, ], }, ], }, { checkboxes: [ { label: 'Show Bookmarks', value: 'Show Bookmarks', checked: bookmarksChecked, onChange: setBookmarksChecked, }, { label: 'Show Full Urls', value: 'Show Full Urls', checked: urlsChecked, onChange: setUrlsChecked, disabled: true, }, { label: 'Show Folders', value: 'Show Folders', checked: foldersChecked, onChange: setFoldersChecked, }, ], }, { label: 'Radio Group', value: person, onChange: setPerson, radios: [ { label: 'Pedro Pascal', value: 'Pedro', }, { label: 'Tom Cruise', value: 'Tom' }, { label: 'Dwayne Johnson', value: 'Dwayne', disabled: true, }, ], }, ]; return ( <V2SplitButton label="Options" menuItems={menuItems} onClick={actionButtonClick} /> ); }; ``` ## onOutsideClick Use `onOutsideClick` prop to trigger a custom function when the user clicks outside an open menu. ```jsx live () => { const actionButtonClick = () => { console.log('Primary Action Clicked'); }; const menuItems = [ { title: 'New Window', onClick: () => { console.log('New Window!'); }, }, { title: 'Open New Tab', onClick: () => { console.log('Open New Tab!'); }, }, { title: 'Save As...', onClick: () => { console.log('Save As...'); }, icon: ( <IconSymbol icon="save" variant="outlined" color="$action-menu-v2.color.text.menu-item.default" /> ), disabled: true, }, ]; return ( <Layout.Group> <V2SplitButton label="Custom Outside Click" menuItems={menuItems} onOutsideClick={(e) => { console.log('Custom Outside Click', e); }} onClick={actionButtonClick} /> </Layout.Group> ); }; ``` ## Dropdown open state Use the `open` and `onOpenChange` props together to control the dropdown open state. `open` is a boolean that determines whether the dropdown is open or closed, and `onOpenChange` is a function that is called when the open state changes. This allows you to manage the open state of the dropdown programmatically. ```jsx live () => { const [controlledOpen, setControlledOpen] = useState(false); const toggleOpen = (newOpenState) => { console.log('new open state', newOpenState); setControlledOpen(newOpenState); }; const actionButtonClick = () => { console.log('Primary Action Clicked'); }; const menuItems = [ { title: 'New Window', onClick: () => { console.log('New Window!'); }, }, { title: 'Open New Tab', onClick: () => { console.log('Open New Tab!'); }, }, { title: 'Save As...', onClick: () => { console.log('Save As...'); }, icon: ( <IconSymbol icon="save" variant="outlined" color="$action-menu-v2.color.text.menu-item.default" /> ), disabled: true, }, ]; return ( <Layout.Group> <V2SplitButton open={controlledOpen} onOpenChange={toggleOpen} label="Open with Controlled State" menuItems={menuItems} onClick={actionButtonClick} /> </Layout.Group> ); }; ``` ## Height Use the `height` prop to set a custom height for the Action Menu. The default height is `500px`. This prop accepts any valid CSS height value. ```jsx live () => { const actionButtonClick = () => { console.log('Primary Action Clicked'); }; const menuItems = [ { title: 'New Window', onClick: () => { console.log('New Window!'); }, }, { title: 'Open New Tab', onClick: () => { console.log('Open New Tab!'); }, }, { title: 'New Private Window', onClick: () => { console.log('New Private Window!'); }, }, { title: 'New Incognito Window', onClick: () => { console.log('New Incognito Window!'); }, }, { title: 'Save As...', onClick: () => { console.log('Save As...'); }, icon: ( <IconSymbol icon="save" variant="outlined" color="$action-menu-v2.color.text.menu-item.default" /> ), }, { title: 'Save All', onClick: () => { console.log('Save All!'); }, icon: ( <IconSymbol icon="save" variant="outlined" color="$action-menu-v2.color.text.menu-item.default" /> ), }, ]; return ( <Layout.Group space={20}> <V2SplitButton label="Options" menuItems={menuItems} onClick={actionButtonClick} height="120" /> </Layout.Group> ); }; ``` ## SplitButton vs. DropdownMenu [V2DropdownMenu](/web/ui/dropdown-menu-v2) is a versatile component that can be used for various menu actions, while `V2SplitButton` is specifically designed for a button with a dropdown menu that allows users to perform an action or select from a list of options. `V2SplitButton` is more suitable when you want to combine a primary action with a secondary dropdown menu. ```jsx live () => { const actionButtonClick = () => { console.log('Primary Action Clicked'); }; const menuItems = [ { title: 'New Private Window', onClick: () => { console.log('Clicked New Private Window!'); }, }, { title: 'Save URL As...', onClick: () => { console.log('Clicked Save URL As'); }, icon: ( <IconSymbol icon="save" variant="outlined" color="$action-menu-v2.color.text.menu-item.default" /> ), }, ]; return ( <Layout.Group space={20}> <V2DropdownMenu outline label="Options" menuItems={menuItems} /> <V2SplitButton label="New Window" menuItems={menuItems} onClick={actionButtonClick} /> </Layout.Group> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2SplitButton" propTypeName="SplitButtonProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="ActionMenu - Menu Item" propTypeName="ActionMenuItemProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="ActionMenu - Checkbox Item" propTypeName="ActionMenuCheckboxItemProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="ActionMenu - Radio Item" propTypeName="ActionMenuRadioItemProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="ActionMenu - Item Group" propTypeName="ActionMenuItemGroupProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="ActionMenu - SubMenu Trigger" propTypeName="SubMenuTriggerProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2ClassesTable title="V2SplitButton" classes={[SplitButtonClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="ActionMenu - Menu Item" classes={[ActionMenuItemClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="ActionMenu - Checkbox Item" classes={[ActionMenuCheckboxItemClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="ActionMenu - Radio Item" classes={[ActionMenuRadioItemClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="ActionMenu - SubMenu Trigger" classes={[SubMenuTriggerClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="ActionMenu - Menu Content" classes={[ActionMenuContentClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="ActionMenu - Menu Separator" classes={[ActionMenuSeparatorClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> <h2>Use for application menu settings and actions only - NOT navigation</h2> From an accessibility and WAI-ARIA perspective, dropdown and split button menus are intended only for application settings and actions—not navigation. Unlike navigation components, these rely solely on arrow keys for making selections. When using navigation components, tabbing between links is an expected behavior. Use [V2NavMenu](/web/ui/nav-menu-v2) or other components for navigating between web pages. <h2>WAI-ARIA implementation</h2> This component implements several WAI-ARIA design patterns beginning with <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/">Menu Button</ExitLink>. Nested menus are of single-menu examples from <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/menubar/">Menu Bar</ExitLink> (using <ExitLink href="https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#keyboardnavigationinsidecomponents">roving tabindex</ExitLink> to manage focus movement). Radio button and checkbox option operation are based upon the <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/menubar/examples/menubar-editor/">Editor Menu Example</ExitLink>. ```jsx live () => { const [bookmarksChecked, setBookmarksChecked] = useState(true); const [urlsChecked, setUrlsChecked] = useState(false); const [person, setPerson] = useState('Paul'); const actionButtonClick = () => { alert('Primary option selected!'); }; const menuItems = [ { title: 'New Window', icon: ( <IconSymbol icon="new_window" variant="outlined" color="$action-menu-v2.color.text.menu-item.default" /> ), onClick: () => { console.log('Clicked New Window!'); }, }, { title: 'New Private Window', icon: ( <IconSymbol icon="security" variant="outlined" color="$action-menu-v2.color.text.menu-item.default" /> ), onClick: () => { console.log('Clicked New Private Window!'); }, disabled: true, }, { title: 'Home', icon: ( <IconSymbol icon="home" variant="outlined" color="$action-menu-v2.color.text.menu-item.default" /> ), onClick: () => { console.log('Clicked Home'); }, }, { title: 'Save options', icon: ( <IconSymbol icon="save" variant="outlined" color="$action-menu-v2.color.text.menu-item.default" /> ), subMenu: [ { title: 'Save', icon: ( <IconSymbol icon="save" variant="outlined" color="$action-menu-v2.color.text.menu-item.default" /> ), onClick: () => { console.log('Clicked Save As'); }, }, { title: 'Save As...', icon: ( <IconSymbol icon="save" variant="outlined" color="$action-menu-v2.color.text.menu-item.default" /> ), onClick: () => { console.log('Clicked Save As'); }, }, { title: 'Save to web...', icon: ( <IconSymbol icon="save" variant="outlined" color="$action-menu-v2.color.text.menu-item.default" /> ), onClick: () => { console.log('Clicked Save to web'); }, }, ], }, { checkboxes: [ { label: 'Show Bookmarks', value: 'Show Bookmarks', checked: bookmarksChecked, onChange: setBookmarksChecked, }, { label: 'Show Full URLs', value: 'Show Full URLs', checked: urlsChecked, onChange: setUrlsChecked, }, ], }, { label: 'Favorite Beatle', value: person, onChange: setPerson, radios: [ { label: 'Pete Best', value: 'Pete', disabled: true, }, { label: 'George Harrison', value: 'George', }, { label: 'John Lennon', value: 'John', }, { label: 'Paul McCartney', value: 'Paul', }, { label: 'Ringo Starr', value: 'Ringo', }, ], }, ]; return ( <React.Fragment> <V2SplitButton label="Options" menuItems={menuItems} onClick={actionButtonClick} /> </React.Fragment> ); }; ``` ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Tab', description: 'Moves focus to the next focusable element.', }, { name: 'Enter', description: 'If focus is on a Dropdown menu button, opens the relevant Dropdown menu. If focus is on a menu item with a trigger, opens the relevant sub-menu. If focus is on radio button or checkbox, will select/deselect it.', }, { name: 'Space', description: 'If focus is on a Dropdown menu button, opens the relevant Dropdown menu. If focus is on a menu item with a trigger, opens the relevant sub-menu. If focus is on radio button or checkbox, will select/deselect it.', }, { name: 'Escape', description: 'Closes open Dropdown menu and moves focus to its Dropdown menu button.', }, { name: 'Up Arrow', description: 'Focuses the previous menu item.', }, { name: 'Down Arrow', description: 'Focuses the next menu item.', }, { name: 'Right Arrow', description: 'Opens a sub-menu if focus is on a menu item with a trigger.', }, { name: 'Left Arrow', description: 'Closes a sub-menu if open.', }, { name: 'Home', description: 'Moves focus to the first item in the Dropdown menu.', }, { name: 'End', description: 'Moves focus to the last item in the Dropdown menu.', }, ]} /> ``` </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={'SplitButton'} keys={['splitButtonV2']} /> ``` ```jsx render <Docs.ComponentTokensTable of={'ActionMenu'} keys={['actionMenuV2']} /> ``` </Tab> --- id: status-indicator category: Data Display title: StatusIndicator description: Provides a status descriptor for UI elements. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=0-992 --- <Tab label="Overview"> ```jsx import { StatusIndicator } from '@uhg-abyss/web/ui/StatusIndicator'; ``` ```jsx render <Docs.V2Deprecated componentName="StatusIndicator" /> ``` ## Usage Use StatusIndicator to display status messages to the user. ```jsx live <StatusIndicator variant="success" statusLabel="Status label"> <StatusIndicator.Icon title="success" /> <StatusIndicator.Text>Status</StatusIndicator.Text> <StatusIndicator.Link href="#">Link</StatusIndicator.Link> </StatusIndicator> ``` ## Variants Use the `variant` property to set the color of the `StatusIndicator`. The options are `success`,`info`,`warning`, and `error`. the default is `success`. ```jsx live <Layout.Stack> <StatusIndicator variant="success" statusLabel="Status label"> <StatusIndicator.Icon title="success" /> <StatusIndicator.Text>Status</StatusIndicator.Text> <StatusIndicator.Link href="#">Link</StatusIndicator.Link> </StatusIndicator> <StatusIndicator variant="info" statusLabel="Status label"> <StatusIndicator.Icon title="info" /> <StatusIndicator.Text>Status</StatusIndicator.Text> <StatusIndicator.Link href="#">Link</StatusIndicator.Link> </StatusIndicator> <StatusIndicator variant="warning" statusLabel="Status label"> <StatusIndicator.Icon title="warning" /> <StatusIndicator.Text>Status</StatusIndicator.Text> <StatusIndicator.Link href="#">Link</StatusIndicator.Link> </StatusIndicator> <StatusIndicator variant="error" statusLabel="Status label"> <StatusIndicator.Icon title="error" /> <StatusIndicator.Text>Status</StatusIndicator.Text> <StatusIndicator.Link href="#">Link</StatusIndicator.Link> </StatusIndicator> </Layout.Stack> ``` ## StatusIndicator.Text Use `StatusIndicator.Text` to specify what status text should appear in the indicator. ```jsx live <Layout.Stack> <StatusIndicator variant="success" statusLabel="Status label"> <StatusIndicator.Text>Success!</StatusIndicator.Text> </StatusIndicator> <StatusIndicator variant="error" statusLabel="Status label"> <StatusIndicator.Text>Error!</StatusIndicator.Text> </StatusIndicator> </Layout.Stack> ``` ## StatusIndicator.Icon Use the `StatusIndicator.Icon` is an element used to set the icon of the `StatusIndicator`. It has a `title` and `variant` property. The variant of the icon can be `success`, `info`, `warning`, or `error`. The icon inherits the variant of the `StatusIndicator` by default. ```jsx live <Layout.Stack> <StatusIndicator variant="success" statusLabel="Status label"> <StatusIndicator.Icon title="success" /> </StatusIndicator> <StatusIndicator variant="warning" statusLabel="Status label"> <StatusIndicator.Icon title="info" variant="info" /> </StatusIndicator> </Layout.Stack> ``` ## StatusIndicator.Link Use the `StatusIndicator.Link` to give the `StatusIndicator` a link. `StatusIndicator.Link` takes in an `href`. ```jsx live <StatusIndicator variant="info" statusLabel="Status label"> <StatusIndicator.Link href="#">Link</StatusIndicator.Link> </StatusIndicator> ``` ## Accessibility Use the `ariaText` prop to provide additional information denoted by the color. For more information visit the accessibility tab. ```jsx live <StatusIndicator ariaText="success" variant="success" statusLabel="Status label" > <StatusIndicator.Link href="#">Link</StatusIndicator.Link> </StatusIndicator> ``` ## Width Use the `width` prop to set the desired width. The default setting is `fit-content`. ```jsx live <StatusIndicator variant="success" statusLabel="Status label" width="100%"> <StatusIndicator.Icon title="success" /> <StatusIndicator.Text>Status</StatusIndicator.Text> <StatusIndicator.Link href="#">Link</StatusIndicator.Link> </StatusIndicator> ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={StatusIndicator} rows={[ { name: 'children', type: 'ReactNode', description: 'StatusIndicator children components', }, { name: 'variant', type: '"success" | "info" | "warning" | "error"', description: 'Set the status type of StatusIndicator', }, { name: 'statusLabel', type: 'string', description: 'Set a label for StatusIndicator', }, { name: 'ariaText', type: 'string', description: 'Set the hidden text used for accessibility purposes', }, { name: 'width', type: 'string | number', description: 'Set the width for StatusIndicator', }, ]} /> ``` ```jsx render <Docs.PropsTable of={StatusIndicator.Icon} rows={[ { name: 'variant', type: '"success" | "info" | "warning" | "error"', description: 'Set the icon type for StatusIcon', }, { name: 'title', type: 'string', description: 'Set the title of the icon', }, ]} /> ``` ```jsx render <Docs.PropsTable of={StatusIndicator.Text} rows={[ { name: 'children', type: 'string', description: 'Display text for StatusIndicator', }, ]} /> ``` ```jsx render <Docs.PropsTable of={StatusIndicator.Link} rows={[ { name: 'children', type: 'string', description: 'Display text StatusLink', }, { name: 'href', type: 'string', description: 'The href for StatusLink', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={StatusIndicator} rows={[ { name: 'status-indicator-root', description: 'StatusIndicator root element', }, { name: 'status-indicator-label', description: 'StatusIndicator label element', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={StatusIndicator.Icon} rows={[ { name: 'status-indicator-icon', description: 'StatusIndicator icon element', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={StatusIndicator.Text} rows={[ { name: 'status-indicator-content', description: 'StatusIndicator content element', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={StatusIndicator.Link} rows={[ { name: 'status-indicator-link', description: 'StatusIndicator link element', }, ]} /> ``` </Tab> <Tab label="Accessibility"> StatusIndicator's are not focusable, visual text elements used to show a status for quick recognition. #### Decorative Icons In the StatusIndicator below, since there is sufficient text next to the icon, the icon is considered decorative and and does not need to be exposed to assistive technology. ```jsx live <Layout.Stack alignItems="left"> <StatusIndicator variant="success" statusLabel="Success"> <StatusIndicator.Icon /> <StatusIndicator.Text>Updates saved</StatusIndicator.Text> </StatusIndicator> <StatusIndicator variant="info" statusLabel="Update"> <StatusIndicator.Icon /> <StatusIndicator.Text>23 attendees</StatusIndicator.Text> </StatusIndicator> <StatusIndicator variant="warning" statusLabel="Warning"> <StatusIndicator.Icon /> <StatusIndicator.Text>Unsaved changes</StatusIndicator.Text> </StatusIndicator> <StatusIndicator variant="error" statusLabel="Error"> <StatusIndicator.Icon /> <StatusIndicator.Text>Unable to save changes</StatusIndicator.Text> </StatusIndicator> </Layout.Stack> ``` #### Meaningful Colors and Icons Color must not be the only means of conveying information or distinguishing elements. Since color provides only a visual indication, similar information needs to be communicated to screen reader users. If color alone or with an icon is used to indicate information, such as a status of "Success", "Warning”, or “Error”, make sure that this information is either part of the visible text content itself or included using the `ariaText` prop. ```jsx live <Layout.Stack alignItems="left"> <StatusIndicator variant="error" ariaText="Error"> <StatusIndicator.Icon /> <StatusIndicator.Text>Unable to save changes</StatusIndicator.Text> </StatusIndicator> <StatusIndicator ariaText="Warning" variant="warning" statusLabel="Status"> <StatusIndicator.Icon /> <StatusIndicator.Text>Taking longer than expected</StatusIndicator.Text> </StatusIndicator> <StatusIndicator ariaText="Success" variant="success" statusLabel="See results" > <StatusIndicator.Link href="#">Link</StatusIndicator.Link> </StatusIndicator> </Layout.Stack> ``` </Tab> --- id: step-indicator category: Content title: StepIndicator description: Used to indicate a user's progress through a multistep process. Also referred to as a progress tracker or stepper. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=0-1578 --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="StepIndicator"></Docs.V2MigrationBanner> ``` ```jsx import { StepIndicator } from '@uhg-abyss/web/ui/StepIndicator'; ``` ```jsx sandbox { component: 'StepIndicator', inputs: [ { prop: 'barColor', type: 'string', }, { prop: 'barSize', type: 'number', }, { prop: 'currentStep', type: 'number', }, { prop: 'stepSize', type: 'number', }, { prop: 'variant', type: 'select', options: [ { label: 'Default', value: 'default' }, { label: 'Minimal', value: 'minimal' }, ] }, ], } <StepIndicator currentStep={3}> <StepIndicator.Step label="Personal Information" /> <StepIndicator.Step label="Qualifications" /> <StepIndicator.Step label="Practice Information" /> <StepIndicator.Step label="Locations" /> <StepIndicator.Step label="Review & Confirm"/> </StepIndicator> ``` ## Usage Use `StepIndicator.Step` as shown below to create as many steps as desired. ```jsx live () => { const paginationProps = usePagination({ pages: 6 }); return ( <React.Fragment> <StepIndicator currentStep={paginationProps.state.currentPage}> <StepIndicator.Step label="Personal Information" /> <StepIndicator.Step label={ <Layout.Group alignLayout="center" space={2}> Qualifications <Popover title="Popover Example" content="Use Popovers to display additional information" ></Popover> </Layout.Group> } /> <StepIndicator.Step label="Practice Information" /> <StepIndicator.Step label="Locations" /> <StepIndicator.Step label="Review & Confirm" /> </StepIndicator> <Layout.Group style={{ marginTop: 10 }}> <Button data-id="1" onClick={paginationProps.previousPage} variant="outline" isDisabled={!paginationProps.canPreviousPage} > Previous </Button> <Button data-id="2" onClick={paginationProps.nextPage} isDisabled={!paginationProps.canNextPage} > Next </Button> </Layout.Group> </React.Fragment> ); }; ``` ## Minimal variant To use the minimal variant, pass in the `variant` prop with a value of `minimal` into the `StepIndicator` component. ```jsx live () => { const paginationProps = usePagination({ pages: 6, start: 1 }); return ( <React.Fragment> <StepIndicator currentStep={paginationProps.state.currentPage} variant="minimal" > <StepIndicator.Step label="Personal Information" /> <StepIndicator.Step label="Qualifications" /> <StepIndicator.Step label="Practice Information" /> <StepIndicator.Step label="Locations" /> <StepIndicator.Step label="Review & Confirm" /> </StepIndicator> <Layout.Group style={{ marginTop: 10 }}> <Button data-id="1" onClick={paginationProps.previousPage} variant="outline" isDisabled={!paginationProps.canPreviousPage} > Previous </Button> <Button data-id="2" onClick={paginationProps.nextPage} isDisabled={!paginationProps.canNextPage} > Next </Button> </Layout.Group> </React.Fragment> ); }; ``` ## Custom incomplete step icons Use `icon` within `StepIndicator.Step` to change the icon of an incomplete step. A full list of icons can be found in the [Icon Component](/web/ui/icon). The default for `icon` is set to each step's position in the list (starting at 1). ```jsx live () => { const paginationProps = usePagination({ pages: 4 }); return ( <React.Fragment> <StepIndicator currentStep={paginationProps.state.currentPage}> <StepIndicator.Step label="Menu" icon={<IconSymbol icon="local_pizza" size="18px" />} /> <StepIndicator.Step label="Checkout" icon={<IconSymbol icon="add_shopping_cart" size="18px" />} /> <StepIndicator.Step label="Delivery" icon={<IconSymbol icon="local_shipping" size="18px" />} /> </StepIndicator> <Layout.Group style={{ marginTop: 10 }}> <Button data-id="1" onClick={paginationProps.previousPage} variant="outline" isDisabled={!paginationProps.canPreviousPage} > Previous </Button> <Button data-id="2" onClick={paginationProps.nextPage} isDisabled={!paginationProps.canNextPage} > Next </Button> </Layout.Group> </React.Fragment> ); }; ``` ## Custom completed step icons Use `icon` within `StepIndicator` to change the icon for all completed steps. A full list of icons can be found in the [Icon Component](/web/ui/icon). The default for `icon` is set to a check mark. ```jsx live () => { return ( <React.Fragment> <StepIndicator icon={<IconSymbol icon="local_pizza" size="18px" />} currentStep={3} > <StepIndicator.Step /> <StepIndicator.Step /> <StepIndicator.Step /> </StepIndicator> </React.Fragment> ); }; ``` ## Pagination Set the `pages` variable to match how many pages you would like to display and `start` to set the starting page. Find resources on pagination in the [usePagination](/web/hooks/use-pagination) tab. ```jsx live () => { const paginationProps = usePagination({ pages: 6 }); return ( <React.Fragment> <StepIndicator currentStep={paginationProps.state.currentPage}> <StepIndicator.Step label="Personal Information" /> <StepIndicator.Step label="Qualifications" /> <StepIndicator.Step label="Practice Information" /> <StepIndicator.Step label="Locations" /> <StepIndicator.Step label="Review & Confirm" /> </StepIndicator> <Layout.Group style={{ marginTop: 10 }}> <Button data-id="1" onClick={paginationProps.previousPage} variant="outline" isDisabled={!paginationProps.canPreviousPage} > Previous </Button> <Button data-id="2" onClick={paginationProps.nextPage} isDisabled={!paginationProps.canNextPage} > Next </Button> </Layout.Group> </React.Fragment> ); }; ``` <br /> If `pages` is set to the number of steps plus one, then the step indicator will be able to create a bar that is completely filled, which would usually be implemented on a "response submitted" style of page. ```jsx live () => { const paginationProps = usePagination({ pages: 6, start: 6 }); return ( <React.Fragment> <StepIndicator currentStep={paginationProps.state.currentPage}> <StepIndicator.Step label="Personal Information" /> <StepIndicator.Step label="Qualifications" /> <StepIndicator.Step label="Practice Information" /> <StepIndicator.Step label="Locations" /> <StepIndicator.Step label="Review & Confirm" /> </StepIndicator> <Layout.Group style={{ marginTop: 10 }}> <Button data-id="1" onClick={paginationProps.previousPage} variant="outline" isDisabled={!paginationProps.canPreviousPage} > Previous </Button> <Button data-id="2" onClick={paginationProps.nextPage} isDisabled={!paginationProps.canNextPage} > Next </Button> </Layout.Group> </React.Fragment> ); }; ``` <br /> If `pages` is set to the number of steps as shown below, the final page will not be able to get checked. ```jsx live () => { const paginationProps = usePagination({ pages: 5, start: 5 }); return ( <React.Fragment> <StepIndicator currentStep={paginationProps.state.currentPage}> <StepIndicator.Step label="Personal Information" /> <StepIndicator.Step label="Qualifications" /> <StepIndicator.Step label="Practice Information" /> <StepIndicator.Step label="Locations" /> <StepIndicator.Step label="Review & Confirm" /> </StepIndicator> <Layout.Group style={{ marginTop: 10 }}> <Button data-id="1" onClick={paginationProps.previousPage} variant="outline" isDisabled={!paginationProps.canPreviousPage} > Previous </Button> <Button data-id="2" onClick={paginationProps.nextPage} isDisabled={!paginationProps.canNextPage} > Next </Button> </Layout.Group> </React.Fragment> ); }; ``` ## Final text in button Use code similar to the example below to change the button on the final page from "Next" to "Submit". ```jsx live () => { const paginationProps = usePagination({ pages: 6, start: 2 }); const buttonMessage = paginationProps.state.currentPage >= paginationProps.state.pageCount - 1 ? 'Submit' : 'Next'; return ( <React.Fragment> <StepIndicator currentStep={paginationProps.state.currentPage}> <StepIndicator.Step label="Personal Information" /> <StepIndicator.Step label="Qualifications" /> <StepIndicator.Step label="Practice Information" /> <StepIndicator.Step label="Locations" /> <StepIndicator.Step label="Review & Confirm" /> </StepIndicator> <Layout.Group style={{ marginTop: 10 }}> <Button data-id="1" onClick={paginationProps.previousPage} variant="outline" isDisabled={!paginationProps.canPreviousPage} > Previous </Button> <Button data-id="2" onClick={paginationProps.nextPage} isDisabled={!paginationProps.canNextPage} > {buttonMessage} </Button> </Layout.Group> </React.Fragment> ); }; ``` ## Horizontal scrolling Use the `horizontalScroll` prop to allow for horizontal scrolling at smaller screen sizes once the steps overflow the parent container. To utilize the default scroll design and functionality, provide the `horizontalScroll` prop as shown below (shrink the window or the size of the Box to see the scrolling). For further configuration of the scroll behavior and design, please use `horizontalScroll` in combination with the [useHorizontalScroll](/web/hooks/use-horizontal-scroll#step-indicator) hook. ```jsx live <Box width="75%"> <StepIndicator horizontalScroll currentStep={3}> <StepIndicator.Step label="Personal Information" /> <StepIndicator.Step label="Document Upload" /> <StepIndicator.Step label="Qualifications" /> <StepIndicator.Step label="References" /> <StepIndicator.Step label="Practice Information" /> <StepIndicator.Step label="Locations" /> <StepIndicator.Step label="Review & Confirm" /> </StepIndicator> </Box> ``` ## Interactive mode Use the `onStepClick` prop to enable user interaction with the StepIndicator. `onStepClick` accepts a function to execute when a step is clicked. The function should accept the step index (i.e., the step number minus one) as an argument. When using the `usePagination` hook as in the example below, the `gotoPage` function returned from the hook will simply set the current step to whichever step was clicked, but additional functionality can be added as needed. The `stepCompletionState` prop is used to track whether each step has been completed. If this prop is not present, the default behavior will be used; that is, a step is marked complete when navigating to the next one and incomplete when navigating to the previous one. In this example, the state is updated to `true` when the user clicks the "Next" or "Previous" buttons, but this can be replaced with any logic that determines when a step is completed. Note that enabling interaction allows the user to navigate between steps without affecting any of the steps' completion state. This can be useful for allowing users to skip around in a process, but it is important to be aware of the implications of doing so, such as: - A user may be able to submit a form without completing all the steps. - A user may be able to navigate to a step that depends on information from a previous step without having completed that step. Developers will be responsible for handling these cases as needed. Note also that in interactive mode, the bar animations are disabled. ```jsx live () => { const { state, gotoPage, previousPage, canPreviousPage, nextPage, canNextPage, } = usePagination({ pages: 6 }); const [stepCompletionState, setStepCompletionState] = useState({ 1: false, 2: false, 3: false, 4: false, 5: false, }); const handleStepClick = (stepIndex) => { console.log('Step index clicked:', stepIndex); gotoPage(stepIndex); }; const handlePreviousClick = (stepNumber) => { setStepCompletionState({ ...stepCompletionState, [stepNumber]: true }); previousPage(); }; const handleNextClick = (stepNumber) => { setStepCompletionState({ ...stepCompletionState, [stepNumber]: true }); nextPage(); }; return ( <React.Fragment> <StepIndicator currentStep={state.currentPage} onStepClick={handleStepClick} stepCompletionState={stepCompletionState} > <StepIndicator.Step label="Personal Information" /> <StepIndicator.Step label="Qualifications" /> <StepIndicator.Step label="Practice Information" /> <StepIndicator.Step label="Locations" /> <StepIndicator.Step label="Review & Confirm" /> </StepIndicator> <Layout.Group css={{ marginTop: 10 }}> <Button onClick={() => { handlePreviousClick(state.currentPage); }} variant="outline" isDisabled={!canPreviousPage} > Previous </Button> <Button onClick={() => { handleNextClick(state.currentPage); }} isDisabled={!canNextPage} > Next </Button> </Layout.Group> </React.Fragment> ); }; ``` Interaction can also be enabled with the minimal variant. ```jsx live () => { const { state, gotoPage, previousPage, canPreviousPage, nextPage, canNextPage, } = usePagination({ pages: 6 }); const [stepCompletionState, setStepCompletionState] = useState({ 1: false, 2: false, 3: false, 4: false, 5: false, }); const handleStepClick = (stepIndex) => { console.log('Step index clicked:', stepIndex); gotoPage(stepIndex); }; const handlePreviousClick = (stepNumber) => { setStepCompletionState({ ...stepCompletionState, [stepNumber]: true }); previousPage(); }; const handleNextClick = (stepNumber) => { setStepCompletionState({ ...stepCompletionState, [stepNumber]: true }); nextPage(); }; return ( <React.Fragment> <StepIndicator currentStep={state.currentPage} onStepClick={handleStepClick} stepCompletionState={stepCompletionState} variant="minimal" > <StepIndicator.Step label="Personal Information" /> <StepIndicator.Step label="Qualifications" /> <StepIndicator.Step label="Practice Information" /> <StepIndicator.Step label="Locations" /> <StepIndicator.Step label="Review & Confirm" /> </StepIndicator> <Layout.Group css={{ marginTop: 10 }}> <Button onClick={() => { handlePreviousClick(state.currentPage); }} variant="outline" isDisabled={!canPreviousPage} > Previous </Button> <Button onClick={() => { handleNextClick(state.currentPage); }} isDisabled={!canNextPage} > Next </Button> </Layout.Group> </React.Fragment> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={StepIndicator} rows={[ { name: 'barSize', type: 'number', description: 'The size of the bar between the icons', default: 'default = 3 | minimal = 2', }, { name: 'barColor', type: 'string', description: 'The color of the bar between the icons', }, { name: 'children', type: 'ReactNode', description: 'The stepper children of StepIndicator', }, { name: 'currentStep', type: 'number', description: 'The current step on the indicator', }, { name: 'stepSize', type: 'number', description: 'Use to set the size of the step icons', default: 'default = 32 | minimal = 16', }, { name: 'icon', type: 'ReactNode', description: 'Use to set the completed icon', default: '<IconSymbol icon="check" size="100%" />', }, { name: 'variant', type: "'default' | 'minimal'", description: 'Use to set variant style', }, { name: 'horizontalScroll ', type: 'boolean | object', description: 'Sets horizontal scrolling for smaller screen sizes', }, { name: 'onStepClick', type: 'function', description: 'If defined, enables user interaction with the StepIndicator. Defines a function to execute when a step is clicked', }, { name: 'stepCompletionState', type: 'object', description: 'If defined, tracks whether each step has been completed. The object should have keys for each step number and values of true or false', }, ]} /> ``` ```jsx render <Docs.PropsTable of={StepIndicator.Step} rows={[ { name: 'icon', type: 'ReactNode', description: 'Use to set an initial icon for the step', }, { name: 'label', type: 'ReactNode', description: 'The labeled text of each step', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={StepIndicator} rows={[ { name: 'step-indicator-container', description: 'Step indicator container element', }, { name: 'step-indicator-root', description: 'Step indicator root element', }, { name: 'step-indicator-scroll-wrapper', description: 'Step indicator wrapper when using horizontal scrolling', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={StepIndicator.Step} rows={[ { name: 'step-indicator-step-root', description: 'Step indicator step root element', }, { name: 'step-indicator-step-bar', description: 'Step indicator step bar element', }, { name: 'step-indicator-step-icon', description: 'Step indicator step icon element', }, { name: 'step-indicator-step-icon-value', description: 'Step indicator step icon value element', }, { name: 'step-indicator-step-label', description: 'Step indicator step label element', }, ]} /> ``` </Tab> <Tab label="Accessibility"> A StepIndicator is used to display a user's progress through a multistep process, such as an input form. It is intended to be an enhancement to, not a replacement for, regular back/next navigation. It is highly recommended to provide meaningful labels for each step, not only for the sake of screen reader users, but also for a clearer visual indication of what each step is. When using the minimal variant, labels are required, as without them, there would be no indication of what the component is beyond its form and color. When using custom icons in the steps instead of the default numbers, it is essential to either provide a meaningful `label` for the step or provide a title to the icon using `isScreenReadable` and `title`. See the [Icon](/web/ui/icon/?tab=integration) documentation for more information on these props. <h2>Differences with Timeline</h2> The [Timeline](/web/ui/timeline) component is similar in appearance and function to StepIndicator, but the two are different in intended use. Whereas Timeline is used to display progress through static content, StepIndicator is used to indicate progress through a process involving user input. ```jsx live () => { const paginationProps = usePagination({ pages: 9 }); const buttonMessage = paginationProps.state.currentPage >= paginationProps.state.pageCount - 1 ? 'Submit' : 'Next'; return ( <React.Fragment> <Box width="50%"> <StepIndicator horizontalScroll currentStep={paginationProps.state.currentPage} > <StepIndicator.Step label="Menu" icon={<IconSymbol icon="local_pizza" size="18px" />} /> <StepIndicator.Step label="Order" icon={<IconSymbol icon="add_shopping_cart" size="18px" />} /> <StepIndicator.Step label="Review" icon={<IconSymbol icon="done_outline" size="18px" />} /> <StepIndicator.Step label="Payment" icon={<IconSymbol icon="credit_card" size="18px" />} /> <StepIndicator.Step label="Prepare Order" icon={<IconSymbol icon="hourglass_empty" size="18px" />} /> <StepIndicator.Step label="Deliver" icon={<IconSymbol icon="local_shipping" size="18px" />} /> <StepIndicator.Step label="Receive Order" icon={<IconSymbol icon="home" size="18px" />} /> <StepIndicator.Step label="Eat Meal" icon={<IconSymbol icon="face" size="18px" />} /> <StepIndicator.Step label="Rate Order" icon={<IconSymbol icon="thumbs_up_down" size="18px" />} /> </StepIndicator> </Box> <Layout.Group style={{ marginTop: 10 }}> <Button data-id="1" onClick={paginationProps.previousPage} variant="outline" isDisabled={!paginationProps.canPreviousPage} > Previous </Button> <Button data-id="2" onClick={paginationProps.nextPage} isDisabled={!paginationProps.canNextPage} > {buttonMessage} </Button> </Layout.Group> </React.Fragment> ); }; ``` ```jsx live () => { return ( <Timeline color={'$interactive1'} active={2}> <Timeline.Item title="Menu"> <Text size="sm">Review our options</Text> </Timeline.Item> <Timeline.Item title="Order"> <Text size="sm">Make your selections</Text> </Timeline.Item> <Timeline.Item title="Review"> <Text size="sm">Confirm order and destination</Text> </Timeline.Item> <Timeline.Item title="Payment"> <Text size="sm">Last step before purchase</Text> </Timeline.Item> <Timeline.Item title="Prepare order"> <Text size="sm">We cook your food</Text> </Timeline.Item> <Timeline.Item title="Delivery"> <Text size="sm">Our drivers come to you</Text> </Timeline.Item> <Timeline.Item title="Receive order"> <Text size="sm">Your meal arrives</Text> </Timeline.Item> <Timeline.Item title="Eat meal"> <Text size="sm">Enjoy your order</Text> </Timeline.Item> <Timeline.Item title="Rate order"> <Text size="sm">Tell us how we did</Text> </Timeline.Item> </Timeline> ); }; ``` </Tab> --- id: step-tracker-v2 category: Content title: V2StepTracker description: Used to indicate a user's progress through a multistep process. Also referred to as a progress tracker or stepper. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=3390-4445 subDirectory: StepTracker sourceIsTS: true --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="StepIndicator"></Docs.V2MigrationBanner> ``` ```jsx import { V2StepTracker } from '@uhg-abyss/web/ui/StepTracker'; ``` ```jsx sandbox-stacked { component: 'V2StepTracker', inputs: [ { prop: 'currentStep', type: 'number', }, { prop: 'hideStepNumbers', type: 'boolean', }, { prop: 'hideStepStatus', type: 'boolean', }, ], } <V2StepTracker steps={[ 'Personal Information', 'Qualifications', 'Practice Information', 'Locations', 'Review & Confirm', ]} currentStep={1} hideStepNumbers={false} hideStepStatus={false} /> ``` ## Usage V2StepTracker works best in conjunction with the [usePagination hook](/web/hooks/use-pagination). `usePagination` handles the state management and provides methods to programmatically update the state externally. There are two ways to provide the labels for the steps, the `steps` prop and child elements. Note that these approaches are mutually exclusive. ### Using the steps prop The simplest method of providing step labels is to use the `steps` prop. This accepts an array of strings and will display the labels in the order provided. ```jsx live-expanded () => { const paginationProps = usePagination({ pages: 6 }); const steps = [ 'Personal Information', 'Qualifications', 'Practice Information', 'Locations', 'Review & Confirm', ]; return ( <React.Fragment> <V2StepTracker steps={steps} currentStep={paginationProps.state.currentPage} /> <Layout.Group style={{ marginTop: 10 }}> <V2Button onClick={paginationProps.previousPage} variant="outline" isDisabled={!paginationProps.canPreviousPage} > Previous </V2Button> <V2Button onClick={paginationProps.nextPage} isDisabled={!paginationProps.canNextPage} > Next </V2Button> </Layout.Group> </React.Fragment> ); }; ``` ### Using child elements If more customization for individual steps is required, such as when styling or adding a `data-testid`, use the V2StepTracker.Step component as the children of the V2StepTracker instead. ```jsx live-expanded () => { const paginationProps = usePagination({ pages: 6 }); return ( <React.Fragment> <V2StepTracker currentStep={paginationProps.state.currentPage}> <V2StepTracker.Step label="Personal Information" data-testid="step-1" /> <V2StepTracker.Step label="Qualifications" /> <V2StepTracker.Step label="Practice Information" /> <V2StepTracker.Step label="Locations" /> <V2StepTracker.Step label="Review & Confirm" /> </V2StepTracker> <Layout.Group style={{ marginTop: 10 }}> <V2Button onClick={paginationProps.previousPage} variant="outline" isDisabled={!paginationProps.canPreviousPage} > Previous </V2Button> <V2Button onClick={paginationProps.nextPage} isDisabled={!paginationProps.canNextPage} > Next </V2Button> </Layout.Group> </React.Fragment> ); }; ``` ## Pagination Set the `pages` variable to match how many pages you would like to display and `start` to set the starting page. If `pages` is set to the number of steps plus one, as shown below, then each step can be marked "Completed". This state would typically be used on a page to indicate that the user has completed the process. ```jsx live () => { const paginationProps = usePagination({ pages: 6, start: 6 }); const steps = [ 'Personal Information', 'Qualifications', 'Practice Information', 'Locations', 'Review & Confirm', ]; return ( <React.Fragment> <V2StepTracker steps={steps} currentStep={paginationProps.state.currentPage} /> <Layout.Group style={{ marginTop: 10 }}> <V2Button onClick={paginationProps.previousPage} variant="outline" isDisabled={!paginationProps.canPreviousPage} > Previous </V2Button> <V2Button onClick={paginationProps.nextPage} isDisabled={!paginationProps.canNextPage} > Next </V2Button> </Layout.Group> </React.Fragment> ); }; ``` If `pages` is set equal to the number of steps, as shown below, the final page will never be marked "Completed". ```jsx live () => { const paginationProps = usePagination({ pages: 5, start: 5 }); const steps = [ 'Personal Information', 'Qualifications', 'Practice Information', 'Locations', 'Review & Confirm', ]; return ( <React.Fragment> <V2StepTracker steps={steps} currentStep={paginationProps.state.currentPage} /> <Layout.Group style={{ marginTop: 10 }}> <V2Button onClick={paginationProps.previousPage} variant="outline" isDisabled={!paginationProps.canPreviousPage} > Previous </V2Button> <V2Button onClick={paginationProps.nextPage} isDisabled={!paginationProps.canNextPage} > Next </V2Button> </Layout.Group> </React.Fragment> ); }; ``` ### Final text in button Use code similar to the example below to change the button on the final page from "Next" to "Submit". ```jsx live () => { const paginationProps = usePagination({ pages: 6 }); const buttonMessage = paginationProps.state.currentPage >= paginationProps.state.pageCount - 1 ? 'Submit' : 'Next'; const steps = [ 'Personal Information', 'Qualifications', 'Practice Information', 'Locations', 'Review & Confirm', ]; return ( <React.Fragment> <V2StepTracker steps={steps} currentStep={paginationProps.state.currentPage} /> <Layout.Group style={{ marginTop: 10 }}> <V2Button onClick={paginationProps.previousPage} variant="outline" isDisabled={!paginationProps.canPreviousPage} > Previous </V2Button> <V2Button onClick={paginationProps.nextPage} isDisabled={!paginationProps.canNextPage} > {buttonMessage} </V2Button> </Layout.Group> </React.Fragment> ); }; ``` ## Hide step numbers Use the `hideStepNumbers` prop to remove the numbers next to each step's label. Note that for accessibility reasons, the numbers will still be read by screen readers. Additionally, even if `hideStepNumbers` is set to `true`, the numbers will still be displayed on the [mobile width](#mobile-width). ```jsx live () => { const paginationProps = usePagination({ pages: 6 }); const steps = [ 'Personal Information', 'Qualifications', 'Practice Information', 'Locations', 'Review & Confirm', ]; return ( <React.Fragment> <V2StepTracker steps={steps} currentStep={paginationProps.state.currentPage} hideStepNumbers /> <Layout.Group style={{ marginTop: 10 }}> <V2Button onClick={paginationProps.previousPage} variant="outline" isDisabled={!paginationProps.canPreviousPage} > Previous </V2Button> <V2Button onClick={paginationProps.nextPage} isDisabled={!paginationProps.canNextPage} > Next </V2Button> </Layout.Group> </React.Fragment> ); }; ``` ## Hide step status Use the `hideStepStatus` prop to remove the step status text. Note that for accessibility reasons, the status will still be read by screen readers. ```jsx live () => { const paginationProps = usePagination({ pages: 6 }); const steps = [ 'Personal Information', 'Qualifications', 'Practice Information', 'Locations', 'Review & Confirm', ]; return ( <React.Fragment> <V2StepTracker steps={steps} currentStep={paginationProps.state.currentPage} hideStepStatus /> <Layout.Group style={{ marginTop: 10 }}> <V2Button onClick={paginationProps.previousPage} variant="outline" isDisabled={!paginationProps.canPreviousPage} > Previous </V2Button> <V2Button onClick={paginationProps.nextPage} isDisabled={!paginationProps.canNextPage} > Next </V2Button> </Layout.Group> </React.Fragment> ); }; ``` ## Mobile width On screens less than 744px wide, the V2StepTracker will only show the current step's title. Resize the window to see the change! ```jsx live () => { const paginationProps = usePagination({ pages: 6 }); const steps = [ 'Personal Information', 'Qualifications', 'Practice Information', 'Locations', 'Review & Confirm', ]; return ( <React.Fragment> <V2StepTracker steps={steps} currentStep={paginationProps.state.currentPage} /> <Layout.Group style={{ marginTop: 10 }}> <V2Button onClick={paginationProps.previousPage} variant="outline" isDisabled={!paginationProps.canPreviousPage} > Previous </V2Button> <V2Button onClick={paginationProps.nextPage} isDisabled={!paginationProps.canNextPage} > Next </V2Button> </Layout.Group> </React.Fragment> ); }; ``` ## Comparison to Timeline [Timeline](/web/ui/timeline-v2) and StepTracker are similar components, but should not be used interchangeably. Both components display a history of completed steps in, the current progress of, and information about the remaining steps in a process. What differentiates one from the other is whether the information displayed is based on immediate user engagement with the user interface or not. ### Timeline The Timeline component is used to inform users of the status of a process with no immediate user input. An example is a claims submission status page where the user can see the progress of their claim through the various stages, but cannot interact with the steps directly. ```jsx live () => { return ( <V2Timeline activeStep={3}> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." completionState="completed" date={dayjs('2025-05-30').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." completionState="completed" date={dayjs('2025-05-31').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." completionState="in-progress" date={dayjs('2025-06-01').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." completionState="not-completed" date={dayjs('2025-06-02').format('MM/DD/YYYY')} /> </V2Timeline> ); }; ``` ### StepTracker The StepTracker is used to guide people through a number of steps to complete in a process. The user navigates through the steps with other components in the UI, typically buttons. An example is a multi-step form where the user fills out information in each step and can navigate back and forth between steps. ```jsx live () => { const paginationProps = usePagination({ pages: 6 }); const steps = [ 'Personal Information', 'Qualifications', 'Practice Information', 'Locations', 'Review & Confirm', ]; return ( <React.Fragment> <V2StepTracker steps={steps} currentStep={paginationProps.state.currentPage} /> <Layout.Group style={{ marginTop: 10 }}> <V2Button onClick={paginationProps.previousPage} variant="outline" isDisabled={!paginationProps.canPreviousPage} > Previous </V2Button> <V2Button onClick={paginationProps.nextPage} isDisabled={!paginationProps.canNextPage} > Next </V2Button> </Layout.Group> </React.Fragment> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2StepTracker" propTypeName="StepTrackerProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="V2StepTracker.Step" propTypeName="ExternalStepTrackerStepProps" /> ``` ```jsx render <Docs.V2ClassesTable title="V2StepTracker" classes={[StepTrackerClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2StepTracker.Step" classes={[StepTrackerStepClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> The StepTracker is used to display a user's progress through a multistep process, such as an input form. It is intended to be an enhancement to, not a replacement for, regular back/next navigation. The following examples can be used to verify screen reader support for the StepTracker using a version with all text visible and a version with optional text hidden. <h2>Full Text</h2> ```jsx live () => { const paginationProps = usePagination({ pages: 6 }); const steps = [ 'Make selection', 'Review', 'Shipping info', 'Payment info', 'Review order', ]; return ( <React.Fragment> <V2StepTracker steps={steps} currentStep={paginationProps.state.currentPage} /> <Layout.Group style={{ marginTop: 10 }}> <V2Button onClick={paginationProps.previousPage} variant="outline" isDisabled={!paginationProps.canPreviousPage} > Previous </V2Button> <V2Button onClick={paginationProps.nextPage} isDisabled={!paginationProps.canNextPage} > Next </V2Button> </Layout.Group> </React.Fragment> ); }; ``` <h2>Minimal Text</h2> ```jsx live () => { const paginationProps = usePagination({ pages: 6 }); const steps = [ 'Make selection', 'Review', 'Shipping info', 'Payment info', 'Review order', ]; return ( <React.Fragment> <V2StepTracker steps={steps} currentStep={paginationProps.state.currentPage} hideStepNumbers hideStepStatus /> <Layout.Group style={{ marginTop: 10 }}> <V2Button onClick={paginationProps.previousPage} variant="outline" isDisabled={!paginationProps.canPreviousPage} > Previous </V2Button> <V2Button onClick={paginationProps.nextPage} isDisabled={!paginationProps.canNextPage} > Next </V2Button> </Layout.Group> </React.Fragment> ); }; ``` </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={'StepTracker'} keys={['stepTrackerV2']} /> ``` </Tab> --- id: sub-navigation-menu category: Navigation title: SubNavigationMenu description: Used to display a navigation menu with links and dropdowns. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=12040-49402 --- <Tab label="Overview"> ```jsx import { SubNavigationMenu } from '@uhg-abyss/web/ui/SubNavigationMenu'; ``` ## Usage Utilize SubNavigationMenu to create a navigation menu on the side of your web page. ```jsx live () => { const title = 'Menu '; const subText = 'Sub menu text'; const navItems = [ { title: 'Active Menu Link', href: '/web/ui/sub-navigation-menu', }, { title: 'Menu Button', onClick: () => { console.log('clicked button'); }, }, { title: 'Menu Link', href: '/web/ui/button', before: ( <IconSymbol icon="info" size={16} title="info" isScreenReadable /> ), after: ( <IconSymbol icon="warning" size={16} title="warning" isScreenReadable /> ), }, { title: 'Menu Link - Open New Window', href: 'https://www.google.com', openNewWindow: true, }, { title: 'Dropdown Item (Lvl 1)', subItems: [ { title: 'Dropdown Item (Lvl 2)', subItems: [ { title: 'Dropdown Link', href: '#', }, ], }, ], }, { title: 'Dropdown Item Link', href: '/web/ui/sub-navigation-menu', removeCollapse: true, subItems: [ { title: 'Dropdown Link', href: '#', }, { title: 'Dropdown Link', href: '#', }, ], }, { title: 'Dropdown Item Button', onClick: () => { console.log('clicked button'); }, subItems: [ { title: 'Dropdown Link', href: '#', }, { title: 'Dropdown Link', href: '#', }, ], }, { title: 'Dropdown Item Disabled', isDisabled: true, onClick: () => { console.log('clicked button'); }, subItems: [ { title: 'Dropdown Link', href: '#', }, { title: 'Dropdown Link', href: '#', }, ], }, ]; return ( <SubNavigationMenu title={title} subText={subText} navItems={navItems} position="right" css={{ 'abyss-sub-navigation-header-container': { position: 'relative', }, 'abyss-sub-navigation-header-text': { '&:after': { content: '', position: 'absolute', borderBottom: '1px solid $gray5', width: '100%', left: 0, bottom: '-8px', }, }, }} /> ); }; ``` ## Scroll When the Menu has overflow it will begin to scroll. ```jsx live () => { const title = 'Menu'; const subText = 'Sub menu text'; const navItems = [ { title: 'Menu Link', href: '#', }, { title: 'Menu Link', href: '/web/ui/button', after: ( <IconSymbol icon="warning" size={16} title="warning" isScreenReadable /> ), }, { title: 'Menu Link', href: '/web/ui/button', openNewWindow: true, }, { title: 'Dropdown item', isOpenByDefault: true, subItems: [ { title: 'Dropdown Link', href: '#', }, { title: 'Dropdown Link', href: '#', }, ], }, { title: 'Dropdown item', subItems: [ { title: 'Dropdown Link', href: '#', }, { title: 'Dropdown Link', href: '#', }, ], }, { title: 'Dropdown item', isDisabled: true, subItems: [ { title: 'Dropdown Link', href: '#', }, { title: 'Dropdown Link', href: '#', }, ], }, ]; return ( <SubNavigationMenu title={title} subText={subText} navItems={navItems} position="right" height="250px" /> ); }; ``` ## Title Use the `title` prop to pass in a title for the Menu. ```jsx live () => { const title = 'Menu'; const navItems = [ { title: 'Menu Link', href: '#', }, { title: 'Menu Link', href: '/web/ui/button', after: ( <IconSymbol icon="warning" size={16} title="warning" isScreenReadable /> ), }, { title: 'Menu Link', href: '/web/ui/button', openNewWindow: true, }, ]; return ( <Layout.Group space={500} alignItems="top"> <SubNavigationMenu title={title} navItems={navItems} position="right" /> </Layout.Group> ); }; ``` ## SubText Use the `subText` prop to pass in a description for the Menu. ```jsx live () => { const title = 'Menu'; const subText = 'Sub menu text'; const navItems = [ { title: 'Menu Link', href: '#', }, { title: 'Menu Link', href: '/web/ui/button', after: ( <IconSymbol icon="warning" size={16} title="warning" isScreenReadable /> ), }, { title: 'Menu Link', href: '/web/ui/button', openNewWindow: true, }, ]; return ( <SubNavigationMenu title={title} subText={subText} navItems={navItems} position="right" /> ); }; ``` ## HeadingLevel Use the `headingLevel` prop to pass in a specified headingLevel for the title. The default is `h3`. When using SubNavigationMenu In `<main>` content (such as a "left nav"): - `it is likely appropriate for titleTag to be a page heading - Set titleTag to "h2" to "h6" to correctly nest in the heading hierarchy (to create` <h2> to <h6>`) As part of a larger navigation element (such as NavMenu): - it is appropriate for titleTag to be an element that correctly nests in the parent - Set titleTag to "div" to create `<div>` or other appropriate child element ```jsx live () => { const title = 'Menu'; const subText = 'Sub menu text'; const navItems = [ { title: 'Menu Link', href: '#', }, { title: 'Menu Link', href: '/web/ui/button', after: ( <IconSymbol icon="warning" size={16} title="warning" isScreenReadable /> ), }, { title: 'Menu Link', href: '/web/ui/button', openNewWindow: true, }, ]; return ( <SubNavigationMenu title={title} subText={subText} navItems={navItems} headingLevel="h4" position="right" /> ); }; ``` ## Width Use the `width` prop to set the width of the menu. Defaults to `320px`. ```jsx live () => { const title = 'Menu'; const subText = 'Sub menu text'; const navItems = [ { title: 'Menu Link', href: '/web/ui/button', after: ( <IconSymbol icon="warning" size={16} title="warning" isScreenReadable /> ), }, { title: 'Menu Link', href: '/web/ui/button', openNewWindow: true, }, { title: 'Menu Link', href: '#', }, { title: 'Menu Link', href: '#', }, { title: 'Menu Link', href: '#', }, { title: 'Menu Link', href: '#', }, { title: 'Menu Link', href: '#', }, ]; return ( <SubNavigationMenu title={title} subText={subText} navItems={navItems} headingLevel="h4" position="right" width="450px" /> ); }; ``` ## Height Use the `height` prop to set the height of the menu. Defaults to `100%`. ```jsx live () => { const title = 'Menu'; const subText = 'Sub menu text'; const navItems = [ { title: 'Menu Link', href: '/web/ui/button', after: ( <IconSymbol icon="warning" size={16} title="warning" isScreenReadable /> ), }, { title: 'Menu Link', href: '/web/ui/button', openNewWindow: true, }, { title: 'Menu Link', href: '#', }, { title: 'Menu Link', href: '#', }, { title: 'Menu Link', href: '#', }, { title: 'Menu Link', href: '#', }, { title: 'Menu Link', href: '#', }, { title: 'Menu Link', href: '#', }, ]; return ( <SubNavigationMenu title={title} subText={subText} navItems={navItems} headingLevel="h4" position="right" height="250px" /> ); }; ``` ## NavItems Use the `navItems` prop to specify what is displayed in the SubNavigationMenu. The prop requires an array of objects that have the form: ```js navItems: [ { title: 'string', href: 'string', isDisabled: 'boolean', before: 'node', after: 'node', onClick: 'func', openNewWindow: 'boolean', subItems: 'object[]', isOpenByDefault: 'boolean', removeCollapse: 'boolean', }, ]; ``` <br /> - `navItems` can have either an `href` or a subset of NavItems in `subItems`. - `navItems` also takes `openNewWindow`, which will open a new window when the link is clicked. If a non-relative path (like https://google.com) is passed, then openNewWindow will be `true` by default; otherwise, it will be `false` by default. - If `subItems` is specified, then the object will be recognized as a dropdown. You can utilize `isOpenByDefault` to specify if the dropdown starts out open or closed (`isOpenByDefault` is set to `false` by default). - `removeCollapse` can be set to true to display all menu sub-items without the collapse functionality. By Default, it is set to `false` and collapse functionality is enabled. - `before` and `after` can be used to place icons or nodes before or after the menu item. ## Set active SubNavigationMenu will inherently determine if the current location path matches a nav-item path and apply the default active state styles. If you'd like to override this default behavior and manually handle setting of the active state, you can use the `setActive` prop. `setActive` is a function that's called as part of a loop through all nav-menu items on render and provides a single argument with each nav-menu item. Return `true` to the item you'd like the default active state styling to be applied. Custom styling can be accomplished by targeting the `abyss-sub-navigation-menu-link-active` class. ```jsx live () => { const title = 'Menu'; const subText = 'Sub menu text'; const navItems = [ { title: 'Home Page', href: '/', }, { title: 'Getting Started', href: '/getting-started', }, ]; const setActive = (menuItem) => { const { getLocation } = useRouter(); const { pathname } = getLocation(); return menuItem.href === pathname; }; const Page = ({ title }) => { return ( <div> <Router.MetaTags> <title>{title}</title> <meta name="description" content={title + 'Page'} /> </Router.MetaTags> <Heading css={{ 'abyss-heading-root': { marginTop: '15px' } }}> {title} Page </Heading> </div> ); }; return ( <RouterProvider history="memory" disableScroll> <SubNavigationMenu title={title} subText={subText} navItems={navItems} position="right" setActive={setActive} /> <Router.Routes> <Router.Route path="/getting-started/" element={<Page title="Getting Started" />} /> <Router.Route path="/" element={<Page title="Home" />} /> </Router.Routes> </RouterProvider> ); }; ``` ## Multi level dropdowns SubNavigationMenu supports up to three levels of dropdown items. To supply an additional level, pass in an array of sub-item objects to the `subItems` property on the sub-item dropdown you'd like it to be applied. ```jsx live () => { const title = 'Multi Level Dropdown'; const subText = 'Sub menu text'; const navItems = [ { title: 'Lvl 1 dropdown', isOpenByDefault: true, subItems: [ { title: 'Lvl 2 dropdown', isOpenByDefault: true, subItems: [ { title: 'Lvl 3 dropdown', isOpenByDefault: true, subItems: [ { title: 'Lvl 4 Link', href: '#', }, ], }, ], }, ], }, { title: 'Lvl 1 dropdown as link', href: '#', subItems: [ { title: 'Lvl 2 dropdown as link', href: '#', subItems: [ { title: 'Lvl 3 link', href: '#', }, ], }, ], }, ]; return ( <SubNavigationMenu title={title} subText={subText} navItems={navItems} position="right" /> ); }; ``` ## Controlled expansion state Use the `expandedItems`, and `onToggleExpansion` props to control open/closed state of dropdowns externally. Both of these props must be provided to enable controlled expansion. Note:: `isOpenByDefault` is no longer applicable when using controlled expansion. ```ts { const [expandedItems, setExpandedItems] = React.useState({ '0': false, '0-0': false, }); const toggleExpansion = (path: string, nextOpen: boolean) => { setExpandedItems((prev) => ({ ...prev, [path]: nextOpen, })); }; //... return ( <SubNavigationMenu expandedItems={expandedItems} onToggleExpansion={toggleExpansion} //... /> ); } ``` ### Default selection example ```jsx live () => { const navItems = [ { title: '0', subItems: [ { title: '0-0', subItems: [ { title: '0-0-0', subItems: [ { title: 'Lvl 4 Link', href: '#', }, ], }, ], }, { title: '0-1', subItems: [ { title: '0-1-0', subItems: [ { title: 'Lvl 4 Link', href: '#', }, ], }, ], }, { title: '0-2', subItems: [ { title: '0-2-0', subItems: [ { title: 'Lvl 4 Link', href: '#', }, ], }, ], }, ], }, { title: '1', subItems: [ { title: '1-0', subItems: [ { title: 'Lvl 3 link', href: '#', }, ], }, ], }, ]; const [expandedItems, setExpandedItems] = React.useState({ 0: true, '0-0': true, '0-0-0': true, '0-2': true, }); const toggleExpansion = (path, nextOpen) => { setExpandedItems((prev) => ({ ...prev, [path]: nextOpen, })); }; const formatExpandedItems = (items) => { const sortedKeys = Object.keys(items).sort((a, b) => { const aParts = a.split('-').map(Number); const bParts = b.split('-').map(Number); for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) { const aVal = aParts[i] ?? -1; const bVal = bParts[i] ?? -1; if (aVal !== bVal) return aVal - bVal; } return 0; }); return JSON.stringify(items, sortedKeys, 2); }; return ( <div style={{ display: 'flex', gap: '2rem' }}> <SubNavigationMenu title={'Controlled expansion'} navItems={navItems} position="right" expandedItems={expandedItems} onToggleExpansion={toggleExpansion} /> <div> <pre style={{ marginTop: '1rem', background: '#f5f5f5', padding: '0.5rem', }} > {formatExpandedItems(expandedItems)} </pre> </div> </div> ); }; ``` ### Closing nested dropdowns when closing parent ```jsx live () => { const navItems = [ { title: '0', subItems: [ { title: '0-0', subItems: [ { title: '0-0-0', subItems: [ { title: 'Lvl 4 Link', href: '#', }, ], }, ], }, { title: '0-1', subItems: [ { title: '0-1-0', subItems: [ { title: 'Lvl 4 Link', href: '#', }, ], }, ], }, { title: '0-2', subItems: [ { title: '0-2-0', subItems: [ { title: 'Lvl 4 Link', href: '#', }, ], }, ], }, ], }, { title: '1', subItems: [ { title: '1-0', subItems: [ { title: 'Lvl 3 link', href: '#', }, ], }, ], }, ]; const [expandedItems, setExpandedItems] = React.useState({ 0: true, '0-0': true, '0-0-0': true, '0-1': true, '0-1-0': true, '0-2': true, '0-2-0': true, }); const toggleExpansion = (path, nextOpen) => { setExpandedItems((prev) => { const next = { ...prev }; // Set the parent open/closed state next[path] = nextOpen; // If closing, also close all children recursively if (!nextOpen) { Object.keys(next).forEach((key) => { // If key starts with path + "-" then it's a child if (key.startsWith(path + '-')) { next[key] = false; } }); } return next; }); }; const formatExpandedItems = (items) => { const sortedKeys = Object.keys(items).sort((a, b) => { const aParts = a.split('-').map(Number); const bParts = b.split('-').map(Number); for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) { const aVal = aParts[i] ?? -1; const bVal = bParts[i] ?? -1; if (aVal !== bVal) return aVal - bVal; } return 0; }); return JSON.stringify(items, sortedKeys, 2); }; return ( <div style={{ display: 'flex', gap: '2rem' }}> <SubNavigationMenu title={'Controlled expansion'} navItems={navItems} position="right" expandedItems={expandedItems} onToggleExpansion={toggleExpansion} /> <div> <pre style={{ marginTop: '1rem', background: '#f5f5f5', padding: '0.5rem', }} > {formatExpandedItems(expandedItems)} </pre> </div> </div> ); }; ``` ### Programmatic control example ```jsx live () => { const navItems = [ { title: '0', subItems: [ { title: '0-0', subItems: [ { title: '0-0-0', subItems: [ { title: 'Lvl 4 Link', href: '#', }, ], }, ], }, { title: '0-1', subItems: [ { title: '0-1-0', subItems: [ { title: 'Lvl 4 Link', href: '#', }, ], }, ], }, { title: '0-2', subItems: [ { title: '0-2-0', subItems: [ { title: 'Lvl 4 Link', href: '#', }, ], }, ], }, ], }, { title: '1', subItems: [ { title: '1-0', subItems: [ { title: 'Lvl 3 link', href: '#', }, ], }, ], }, ]; const [expandedItems, setExpandedItems] = React.useState({}); const toggleExpansion = (path, nextOpen) => { setExpandedItems((prev) => ({ ...prev, [path]: nextOpen, })); }; const cascadeExpansion = (path, nextOpen) => { setExpandedItems((prev) => { let next = { ...prev }; next[path] = nextOpen; if (!nextOpen) { Object.keys(next).forEach((key) => { if (key.startsWith(path + '-')) { next[key] = false; } }); } else { const parts = path.split('-'); for (let i = 1; i < parts.length; i++) { const ancestorPath = parts.slice(0, i).join('-'); next[ancestorPath] = true; } } return next; }); }; const formatExpandedItems = (items) => { const sortedKeys = Object.keys(items).sort((a, b) => { const aParts = a.split('-').map(Number); const bParts = b.split('-').map(Number); for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) { const aVal = aParts[i] ?? -1; const bVal = bParts[i] ?? -1; if (aVal !== bVal) return aVal - bVal; } return 0; }); return JSON.stringify(items, sortedKeys, 2); }; return ( <div style={{ display: 'flex', gap: '2rem' }}> <SubNavigationMenu title={'Controlled expansion'} navItems={navItems} position="right" expandedItems={expandedItems} onToggleExpansion={toggleExpansion} /> <div> <div style={{ display: 'flex', flexWrap: 'wrap', gap: '1rem' }}> <Button onClick={() => cascadeExpansion('0-2-0', true)}> Open Deep Nested Item </Button> <Button onClick={() => cascadeExpansion('0', false)}> Close Parent and All Children </Button> </div> <div> <pre style={{ marginTop: '1rem', background: '#f5f5f5', padding: '0.5rem', }} > {formatExpandedItems(expandedItems)} </pre> </div> </div> </div> ); }; ``` ## Clickable header title To render the SubNavigationMenu header title as a link, pass in an href to the `titleHref` prop. To render as a button, pass in a callback function to `titleOnClick`. ### titleHref ```jsx live () => { const title = 'Menu'; const subText = 'Sub menu text'; const navItems = [ { title: 'Menu Link', href: '#', }, { title: 'Menu Link', href: '#', }, ]; return ( <SubNavigationMenu title={title} subText={subText} navItems={navItems} titleHref="/web/ui/sub-navigation-menu" /> ); }; ``` ### titleOnClick ```jsx live () => { const title = 'Menu'; const subText = 'Sub menu text'; const navItems = [ { title: 'Menu Link', href: '#', }, { title: 'Menu Link', href: '#', }, ]; return ( <SubNavigationMenu title={title} subText={subText} navItems={navItems} titleOnClick={() => { console.log('header title clicked'); }} /> ); }; ``` ## Side bar menu Pass in the prop `variant` and set the value to `sideBarMenu` in order to turn your SubNavigationMenu into a side bar menu that lists out all available links. ```jsx live () => { const sideBarTitle = 'Sidebar Menu'; const sideBarMenuItems = [ { title: 'Dropdown link', href: '/web/ui/sub-navigation-menu', }, { title: 'Dropdown link', href: '#', }, { title: 'Dropdown link', href: '#', }, { title: 'Dropdown link', href: '#', }, { title: 'Dropdown link', href: '#', }, ]; return ( <SubNavigationMenu title={sideBarTitle} navItems={sideBarMenuItems} position="right" variant="sideBarMenu" width="200px" /> ); }; ``` ### Position Set the `position` prop to `left` when aligning the sideBarMenu variant to the right side of the screen. This will move the active indicator to the left side and update the menu alignment. `position` is set to `right` by default ```jsx live () => { const sideBarTitle = 'Sidebar Menu'; const sideBarMenuItems = [ { title: 'Dropdown link', href: '/web/ui/sub-navigation-menu', }, { title: 'Dropdown link', href: '#', }, { title: 'Dropdown link', href: '#', }, { title: 'Dropdown link', href: '#', }, { title: 'Dropdown link', href: '#', }, ]; return ( <Layout.Group alignLayout="right"> <SubNavigationMenu title={sideBarTitle} navItems={sideBarMenuItems} position="left" variant="sideBarMenu" width="200px" /> </Layout.Group> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={SubNavigationMenu} rows={[ { name: 'title', type: 'string', description: 'Title of the SubNavigrationMenu', }, { name: 'subText', type: 'string', description: 'Description of the SubNavigationMenu', }, { name: 'onClick', type: 'function', description: 'Callback fired when the dropdown is clicked', }, { name: 'navItems', type: 'object[]', description: 'Array of menu items. { title: string, isDisabled: boolean, href: string, before: node, after: node, isOpenByDefault: boolean, subItems: object[], openNewWindow: boolean, onClick: function, isActive: boolean, removeCollapse: boolean}', }, { name: 'position', type: 'left | right', description: 'Positions nav on the left or right side', }, { name: 'width', type: ' string | number', description: 'changes the width of the menu', }, { name: 'height', type: 'string | number', description: 'changes the height of the menu. Defaults to 100%', }, { name: 'variant', type: 'default | sideBarMenu', description: 'changes SubNavigationMenu into a sideBarMenu', }, { name: 'headingLevel', type: 'h1 | h2 | h3 | h4 | h5 | h6', description: 'changes the heading level of the title. defaults to h3', }, { name: 'setActive', type: 'function', description: 'Callback function to manually set active state for nav-menu links', }, { name: 'titleHref', type: 'string', description: 'Adds a link to SubNavigationMenu header title', }, { name: 'titleOnClick', type: 'function', description: 'Callback function fired when SubNavigationMenu header title is clicked', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={SubNavigationMenu} rows={[ { name: 'sub-navigation-menu-root', description: 'root element', }, { name: 'sub-navigation-header-container', description: 'Header container', }, { name: 'sub-navigation-header-title', description: 'Header title', }, { name: 'sub-navigation-header-text', description: 'Header subText', }, { name: 'sub-navigation-menu-items', description: 'Menu items unordered list', }, { name: 'sub-navigation-menu-item', description: 'Menu List item', }, { name: 'sub-navigation-menu-link', description: 'Menu Link', }, { name: 'sub-navigation-menu-link-active', description: 'Menu Link Active', }, { name: 'sub-navigation-dropdown-button', description: 'Dropdown button', }, { name: 'sub-navigation-dropdown-container', description: 'Dropdown container', }, { name: 'sub-navigation-dropdown-wrapper', description: 'Dropdown wrapping title and button', }, { name: 'sub-navigation-dropdown-button-chevron', description: 'Button Chevron', }, { name: 'sub-navigation-dropdown-title', description: 'Dropdown title/link', }, { name: 'sub-navigation-dropdown-list-container', description: 'Dropdown links container', }, ]} /> ``` </Tab> <Tab label= 'Accessibility'> For icon accessibility please refer to [Icon Material](/web/ui/icon-material). SubNavigationMenu is a <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/treeview/">WAI-ARIA Tree View pattern</ExitLink> that follows the <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/treeview/examples/treeview-navigation/"> Navigation Treeview Example</ExitLink> AND "Disclosure" approach described in the notes. This is so default operation is more predictable using tabs for website navigation. Arrow key implementation is more appropriate to a web application. ```jsx live () => { const title = 'Basic site'; const subText = 'Sample navigation option'; const navItems = [ { title: 'Welcome', href: '/web/ui/sub-navigation-menu', }, { title: 'Open', onClick: () => { console.log('clicked button'); }, }, { title: 'About us', href: '/web/ui/button', before: ( <IconSymbol icon="info" size={16} title="info" isScreenReadable /> ), after: ( <IconSymbol icon="warning" size={16} title="Work in progress" isScreenReadable /> ), }, { title: 'Google search', href: 'https://www.google.com', openNewWindow: true, }, { title: 'Other search options', subItems: [ { title: 'Microsoft', subItems: [ { title: 'Bing', href: 'http://bing.com', openNewWindow: true, }, ], }, ], }, { title: 'Our offerings', href: '#', removeCollapse: true, subItems: [ { title: 'Features', href: '#', }, { title: 'Support options', href: '#', }, ], }, { title: 'Purchase options', onClick: () => { console.log('clicked button'); }, subItems: [ { title: 'Standard financing', href: '#', }, { title: 'Other options', href: '#', }, ], }, { title: 'Future items (TBD)', isDisabled: true, onClick: () => { console.log('clicked button'); }, subItems: [ { title: 'Holodeck', href: '#', }, { title: 'Transporter', href: '#', }, ], }, { title: 'Good-bye!', href: '#', }, ]; return ( <SubNavigationMenu title={title} subText={subText} navItems={navItems} position="right" css={{ 'abyss-sub-navigation-header-container': { position: 'relative', }, 'abyss-sub-navigation-header-text': { '&:after': { content: '', position: 'absolute', borderBottom: '1px solid $gray5', width: '100%', left: 0, bottom: '-8px', }, }, }} /> ); }; ``` ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Tab', description: 'Traverse the SubNavMenu', }, { name: 'Enter', description: 'Select a SubNavMenu item. When hitting Enter on a dropdown, it will open/close the dropdown', }, { name: 'Down Arrow', description: 'Moves focus to the next node that is focusable without opening or closing a node', }, { name: 'Up Arrow', description: 'Moves focus to the previous node that is focusable without opening or closing a node', }, { name: 'Home', description: 'Moves focus to the first node in the tree without opening or closing a node', }, { name: 'End', description: 'Moves focus to the last node in the tree that is focusable without opening a node', }, { name: 'Right Arrow', description: 'Focus is on a closed dropdown, opens the dropdown; focus does not move', }, { name: 'Left Arrow', description: 'Focus is on an open dropdown, closes the dropdown', }, { name: 'A-Z or a-z', description: 'Moves focus to the next menu item with a label that starts with the typed character if such an menu item exists. Otherwise, focus does not move', }, ]} /> ``` </Tab> --- id: table category: Data Display title: Table description: Used to create a static table of data to easily convey information. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=22159-101294 --- <Tab label="Overview"> ```jsx import { Table } from '@uhg-abyss/web/ui/Table'; ``` ## Usage A `Table` is used strictly for HTML markup on the page. It is a static tabular structure containing one or more rows that each contain one or more cells; it is not an interactive widget. Thus, its cells are not focusable or selectable. They organize information in a way that's easy to scan so that users can look for patterns and develop insights from data. The table consists of the `Table Header` and the `Table Body`. Column header names describe the type of content displayed in each column. Column header text uses a medium weight font to differentiate from row text. Each row contains data related to a single entity. If you want to turn a `column` or `FooterCell` into a row header, pass the `isRowHeader: true` prop to an individual column or cell . ```jsx live () => { const columns = [ { name: 'Name', key: 'name', isRowHeader: true }, { name: 'Type', key: 'type' }, { name: 'Date Modified', key: 'date' }, { name: 'Rating', key: 'rating' }, ]; const rows = [ { id: 1, name: 'Games', date: '6/7/2020', type: 'File folder', rating: 2 }, { id: 2, name: 'Program Files', date: '4/7/2021', type: 'File folder', rating: 3, }, { id: 3, name: 'bootmgr', date: '11/20/2010', type: 'System file', rating: 2, }, { id: 4, name: 'log.txt', date: '1/18/2016', type: 'Text Document', rating: 1, }, ]; const footer = ( <Table.Row> <Table.FooterCell isRowHeader colSpan={3}> Avg. Rating </Table.FooterCell> <Table.FooterCell>2</Table.FooterCell> </Table.Row> ); return ( <Table title="Base Static Table" columns={columns} rows={rows} footer={footer} /> ); }; ``` ## Table overflow scroll The contents of a table can be made scrollable if there is not enough space to show the entire table at once. To do so, use a wrapper element like in the example below, setting the CSS `overflow` property to `'auto'` and adding a `tabindex` of 0. ```jsx live () => { const columns = [ { name: 'Name', key: 'name' }, { name: 'Type', key: 'type' }, { name: 'Content Size', key: 'size' }, { name: 'Upload By', key: 'uploadby' }, { name: 'Date Created', key: 'creationdate' }, { name: 'Date Modified', key: 'date' }, { name: 'Organization', key: 'org' }, { name: 'Team', key: 'team' }, { name: 'Location', key: 'location' }, { name: 'Status', key: 'status' }, { name: 'Approval', key: 'approval' }, ]; const rows = [ { id: 1, name: 'Games', size: '5GB', uploadby: 'SK', date: '6/7/2020', type: 'File folder', creationdate: '5/7/2020', org: 'Optum', team: 'Abyss', location: 'MN', status: 'Completed', approval: 'Manager', }, { id: 2, name: 'Program Files', size: '50GB', uploadby: 'AB', date: '4/7/2021', type: 'File folder', creationdate: '2/7/2021', org: 'Optum', team: 'Abyss', location: 'MN', status: 'Completed', approval: 'Manager', }, { id: 3, name: 'bootmgr', size: '100GB', uploadby: 'SK', date: '11/20/2010', type: 'System file', creationdate: '11/10/2009', org: 'Optum', team: 'Abyss', location: 'MN', status: 'Pending', approval: 'Manager', }, { id: 4, name: 'log.txt', size: '5KB', uploadby: 'TK', date: '1/18/2016', type: 'Text Document', creationdate: '1/1/2016', org: 'Optum', team: 'Abyss', location: 'MN', status: 'Review', approval: 'Manager', }, ]; const WrapperDiv = styled('div', { overflow: 'auto' }); return ( <WrapperDiv tabIndex={0}> <Table title="Table Scroll" columns={columns} rows={rows} /> </WrapperDiv> ); }; ``` ## Manual table If more customization is needed, use the `Table` sub-components to create each section. This allows for adjustments to the individual sections. ```jsx live <Table.Container title="Manual Static Table"> <Table.TableHeader> <Table.TableHeaderRow> <Table.Column>Name</Table.Column> <Table.Column>Type</Table.Column> <Table.Column>Date Modified</Table.Column> <Table.Column>Rating</Table.Column> </Table.TableHeaderRow> </Table.TableHeader> <Table.TableBody> <Table.Row> <Table.Cell>Games</Table.Cell> <Table.Cell>File folder</Table.Cell> <Table.Cell>6/7/2020</Table.Cell> <Table.Cell>2</Table.Cell> </Table.Row> <Table.Row> <Table.Cell>Program Files</Table.Cell> <Table.Cell>File folder</Table.Cell> <Table.Cell>4/7/2021</Table.Cell> <Table.Cell>3</Table.Cell> </Table.Row> <Table.Row> <Table.Cell>bootmgr</Table.Cell> <Table.Cell>System file</Table.Cell> <Table.Cell>11/20/2010</Table.Cell> <Table.Cell>2</Table.Cell> </Table.Row> <Table.Row> <Table.Cell>log.txt</Table.Cell> <Table.Cell>Text Document</Table.Cell> <Table.Cell>1/18/2016</Table.Cell> <Table.Cell>1</Table.Cell> </Table.Row> </Table.TableBody> <Table.TableFooter> <Table.Row> <Table.FooterCell colSpan={3}>Avg. Rating</Table.FooterCell> <Table.FooterCell>2</Table.FooterCell> </Table.Row> </Table.TableFooter> </Table.Container> ``` ## Custom table If further customization is needed, most styles of `Table` can be overridden using `css`. ```jsx live <Table.Container title="Manual Static Table"> <Table.TableHeader> <Table.TableHeaderRow css={{ color: '$white', backgroundColor: '$black' }}> <Table.Column>Name</Table.Column> <Table.Column>Type</Table.Column> <Table.Column>Date Modified</Table.Column> </Table.TableHeaderRow> </Table.TableHeader> <Table.TableBody> <Table.Row> <Table.Cell css={{ color: '$primary1', backgroundColor: '$gray3' }}> Games </Table.Cell> <Table.Cell>File folder</Table.Cell> <Table.Cell css={{ color: '$primary2', backgroundColor: '$primary1' }}> 6/7/2020 </Table.Cell> </Table.Row> <Table.Row> <Table.Cell css={{ color: '$primary1', backgroundColor: '$gray3' }}> Program Files </Table.Cell> <Table.Cell>File folder</Table.Cell> <Table.Cell css={{ color: '$primary2', backgroundColor: '$primary1' }}> 4/7/2021 </Table.Cell> </Table.Row> </Table.TableBody> </Table.Container> ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={Table} rows={[ { name: 'children', type: 'ReactNode', description: 'The contents of the table component', }, { name: 'title', type: 'string', description: 'Title of the table', }, { name: 'columns', type: 'array[object]', description: 'Array of column data. { name: string, key: string }', }, { name: 'rows', type: 'array[object]', description: 'Array of column data. { id: number, [column key]: string }', }, { name: 'highlightRowOnHover', type: 'boolean', description: 'Adds highlighting of rows on hover', }, ]} /> ``` ```jsx render <Docs.PropsTable of={Table.Container} rows={[ { name: 'children', type: 'ReactNode', description: 'The contents of the table container component', }, { name: 'title', type: 'string', description: 'Title of the table', }, ]} /> ``` ```jsx render <Docs.PropsTable of={Table.TableHeader} rows={[ { name: 'children', type: 'ReactNode', description: 'The contents of the table header component', }, ]} /> ``` ```jsx render <Docs.PropsTable of={Table.TableHeaderRow} rows={[ { name: 'children', type: 'ReactNode', description: 'The contents of the table header row component', }, ]} /> ``` ```jsx render <Docs.PropsTable of={Table.Column} rows={[ { name: 'children', type: 'ReactNode', description: 'The contents of the table header column component', }, { name: 'isRowHeader', type: 'boolean', description: 'Whether a column is a row header and should be announced by assistive technology during row navigation.', }, ]} /> ``` ```jsx render <Docs.PropsTable of={Table.TableBody} rows={[ { name: 'children', type: 'ReactNode', description: 'The contents of the table body component', }, ]} /> ``` ```jsx render <Docs.PropsTable of={Table.Row} rows={[ { name: 'children', type: 'ReactNode', description: 'The contents of the table row component', }, ]} /> ``` ```jsx render <Docs.PropsTable of={Table.Cell} rows={[ { name: 'children', type: 'ReactNode', description: 'The contents of the table cell component', }, { name: 'isRowHeader', type: 'boolean', description: 'Whether a cell is a row header and should be announced by assistive technology during row navigation.', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Table} rows={[ { name: 'table-root', description: 'Table root element', }, { name: 'table-head', description: 'Header container', }, { name: 'table-styled-header', description: 'Header Styled Container', }, { name: 'table-styled-header-col-${colNum}', description: 'Header styled cell container in the given column', }, { name: 'table-header-data', description: 'Header Cell Container', }, { name: 'table-header-container', description: 'Header Container', }, { name: 'table-header-cell-container', description: 'Header cell container', }, { name: 'table-footer', description: 'Footer', }, { name: 'table-footer-row', description: 'Footer row', }, { name: 'table-footer-cell', description: 'Footer cell', }, { name: 'table-footer-cell-col-{colNum}', description: 'Footer cell element in the given column', }, { name: 'table-body', description: 'Body container', }, { name: 'table-row', description: 'Row element', }, { name: 'table-row-{rowNum}', description: 'Row element with the given number', }, { name: 'table-row-expanded', description: 'Row expanded', }, { name: 'table-row-expanded-row-{rowNum}', description: 'Row expanded for the given row', }, { name: 'table-cell', description: 'Cell element', }, { name: 'table-cell-col-{colNum}-row-{rowNum}', description: 'Cell element in the given column and row', }, { name: 'table-cell-expanded', description: 'Cell expanded', }, { name: 'table-cell-expanded-row-{rowNum}', description: 'Cell expanded for the given row', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Table.Container} rows={[ { name: 'table-root', description: 'Table root element', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Table.TableHeader} rows={[ { name: 'table-head', description: 'Header container', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Table.TableHeaderRow} rows={[ { name: 'table-header', description: 'Header row container', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Table.Column} rows={[ { name: 'table-styled-header', description: 'Header styled cell container', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Table.TableBody} rows={[ { name: 'table-body', description: 'Body container', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Table.Row} rows={[ { name: 'table-row', description: 'Row element', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Table.Cell} rows={[ { name: 'table-cell', description: 'Cell element', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Table.FooterCell} rows={[ { name: 'table-footer-cell', description: 'Footer cell element', }, ]} /> ``` </Tab> <Tab label="Accessibility"> Like an HTML table element, a WAI-ARIA table is a static tabular structure containing one or more rows that each contain one or more cells; it is not an interactive widget. Thus, its cells are not focusable or selectable. The grid pattern is used to make an interactive widget that has a tabular structure. However, tables are often used to present a combination of information and interactive widgets. Since a table is not a widget, each widget contained in a table is a separate stop in the page tab sequence. If the number of widgets is large, replacing the table with a grid can dramatically reduce the length of the page tab sequence because a grid is a composite widget that can contain other widgets. Adheres to the <ExitLink href="https://www.w3.org/TR/wai-aria-practices-1.2/#table">Table WAI-ARIA design pattern</ExitLink>. ```jsx live () => { const columns = [ { name: 'Name', key: 'name', isRowHeader: true }, { name: 'Breed', key: 'breed' }, { name: 'Sex', key: 'sex' }, { name: 'Age', key: 'age' }, ]; const rows = [ { id: 1, name: 'Snoopy', breed: 'Beagle', sex: 'Male', age: '12', }, { id: 2, name: 'Lady', breed: 'Cocker Spaniel', sex: 'Female', age: '3', }, { id: 3, name: 'Tramp', breed: 'Mixed breed', sex: 'Male', age: '7', }, { id: 4, name: 'Rin Tin Tin', breed: 'German Shepherd', sex: 'Male', age: '5', }, ]; return <Table title="Dog registry" columns={columns} rows={rows} />; }; ``` ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Not Applicable', description: 'Not Applicable', }, ]} /> ``` </Tab> --- id: tabs-v2 category: Content title: V2Tabs description: Used to view and switch between different sets of content. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=10585-1594 subDirectory: Tabs/v2 sourceIsTS: true --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="Tabs"></Docs.V2MigrationBanner> ``` ```jsx import { V2Tabs } from '@uhg-abyss/web/ui/Tabs'; ``` ```jsx sandbox { component: 'V2Tabs', inputs: [ { prop: 'initialTab', type: 'number', description: 'Used to indicate initial tab', }, { prop: 'height', type: 'string', description: 'Set size of tabs', }, { prop: 'display', type: 'select', options: [ { label: 'row', value: 'row' }, { label: 'column', value: 'column' }, ], }, ] } <V2Tabs title="Tabs Sandbox"> <V2Tabs.Tab label="Tab 1">Tab 1 Content</V2Tabs.Tab> <V2Tabs.Tab label="Tab 2">Tab 2 Content</V2Tabs.Tab> <V2Tabs.Tab label="Tab 3">Tab 3 Content</V2Tabs.Tab> </V2Tabs> ``` ## Display The `display` property determines whether the tab buttons will be displayed horizontally or vertically. The two options are `row` and `column`, and the default is `row`. Additionally, the `height` property is only applicable to `column` display. ```jsx live <Layout.Stack grow space={45}> <V2Tabs title="Display - Row"> <V2Tabs.Tab label="Row Display - Tab 1">Tab 1 Content</V2Tabs.Tab> <V2Tabs.Tab label="Row Display - Tab 2">Tab 2 Content</V2Tabs.Tab> <V2Tabs.Tab label="...Tab 3">Tab 3 Content</V2Tabs.Tab> </V2Tabs> <V2Tabs title="Display - Column" display="column"> <V2Tabs.Tab label="Column Display - Tab 1">Tab 1 Content</V2Tabs.Tab> <V2Tabs.Tab label="Column Display - Tab 2">Tab 2 Content</V2Tabs.Tab> <V2Tabs.Tab label="...Tab 3">Tab 3 Content</V2Tabs.Tab> </V2Tabs> </Layout.Stack> ``` ## Title The `title` property provides a label that describes the purpose of the set of tabs. This is a required property, as it gives screen reader users important context. ```jsx <V2Tabs title="Tab Group Title"> <V2Tabs.Tab label="Tab - 1">Tab 1 Content</V2Tabs.Tab> <V2Tabs.Tab label="Tab - 2">Tab 2 Content</V2Tabs.Tab> <V2Tabs.Tab label="Tab - 3">Tab 3 Content</V2Tabs.Tab> </V2Tabs> ``` ## Labels Use the `label` prop for the individual tabs to succinctly describe their content. To add more content to the tabs, we provide the props `subLabel`, `leftAddOn`, and `rightAddOn`. `subLabel` can be used to provide additional context to the tab label. `leftAddOn` and `rightAddOn` take in any `React.ReactElement`, such as an `IconSymbol` or `V2Badge`, to provide additional information next to the `label`. Note: It is recommended by the Abyss Design System to keep `rightAddOn` as a [Badge](/web/ui/badge-v2), while `leftAddOn` can be completely custom. ```jsx live () => { return ( <V2Tabs title="Extra Tabs"> <V2Tabs.Tab label="Tab 1" subLabel="sub label" rightAddOn={<V2Badge variant="info">Info</V2Badge>} > Tab 1 content </V2Tabs.Tab> <V2Tabs.Tab label="Tab 2" subLabel="sub label"> Tab 2 Content </V2Tabs.Tab> <V2Tabs.Tab label="Tab 3" subLabel="sub label" leftAddOn={<IconSymbol icon="star" size={16} />} > Tab 3 Content </V2Tabs.Tab> </V2Tabs> ); }; ``` ## Overflow When there are too many tabs to fit above the content container, the design automatically changes to account for the overflow. Clicking on tabs will scroll them into view, but all tabs are also displayed in a drawer for viewing. In the drawer, tabs are still navigable with arrow keys. This view is especially applicable for mobile devices. ```jsx live <Box width="100%"> <V2Tabs title="Display - Overflow"> <V2Tabs.Tab label="Overflow Tab 1">Tab 1 Content</V2Tabs.Tab> <V2Tabs.Tab label="Overflow Tab 2">Tab 2 Content</V2Tabs.Tab> <V2Tabs.Tab label="Overflow Tab 3">Tab 3 Content</V2Tabs.Tab> <V2Tabs.Tab label="Overflow Tab 4">Tab 4 Content</V2Tabs.Tab> <V2Tabs.Tab label="Overflow Tab 5">Tab 5 Content</V2Tabs.Tab> <V2Tabs.Tab label="Overflow Tab 6">Tab 6 Content</V2Tabs.Tab> <V2Tabs.Tab label="Overflow Tab 7">Tab 7 Content</V2Tabs.Tab> <V2Tabs.Tab label="Overflow Tab 8">Tab 8 Content</V2Tabs.Tab> </V2Tabs> </Box> ``` ## Max width Use the `maxWidth` prop for the individual tabs to have a maxWidth, after which the `label` and `subLabel` text will wrap. ```jsx live () => { return ( <V2Tabs title="Extra Tabs"> <V2Tabs.Tab label="Tab 1 wrapping with lorem ipsum dolor sit amet" subLabel="Lorem ipsum dolor sit amet, consectetur adipiscing elit" rightAddOn={<V2Badge variant="info">Info</V2Badge>} maxWidth="200px" > Tab 1 content </V2Tabs.Tab> <V2Tabs.Tab label="Tab 2" subLabel="sub label"> Tab 2 Content </V2Tabs.Tab> <V2Tabs.Tab label="Tab 3" subLabel="sub label"> Tab 3 Content </V2Tabs.Tab> </V2Tabs> ); }; ``` ## Active (controlled) To control the tabs active state, pass in the index of the desired tab to the `active` prop. This must be used in combination with `onTabChange` to ensure that the active tab state is always current. If no default state is passed, the active tab will default to the first tab in the sequence. ```jsx live () => { const [activeIndex, setActiveIndex] = useState(1); return ( <Layout.Stack alignItems="left" grow> <V2Tabs title="Active Tab" active={activeIndex} onTabChange={setActiveIndex} > <V2Tabs.Tab label="Tab - 1">Tab 1 Content</V2Tabs.Tab> <V2Tabs.Tab label="Tab - 2">Tab 2 Content</V2Tabs.Tab> <V2Tabs.Tab label="Tab - 3">Tab 3 Content</V2Tabs.Tab> </V2Tabs> <Layout.Group> <V2Button onClick={() => setActiveIndex(0)}>Set to Tab 1</V2Button> <V2Button onClick={() => setActiveIndex(1)}>Set to Tab 2</V2Button> <V2Button onClick={() => setActiveIndex(2)}>Set to Tab 3</V2Button> </Layout.Group> </Layout.Stack> ); }; ``` ## Initial tab (uncontrolled) If you do not need to subscribe to the tabs active state, use the `initialTab` property to set the tab that is active at build time. The default is set to the first tab in the sequence. If used instead of `active` the active state will be uncontrolled and handled internally by the component. ```jsx live <V2Tabs initialTab={2} title="Initial Tab"> <V2Tabs.Tab label="Other Tab - 1">Tab 1 Content</V2Tabs.Tab> <V2Tabs.Tab label="Initial Tab - 2">Tab 2 Content</V2Tabs.Tab> <V2Tabs.Tab label="Other Tab - 3">Tab 3 Content</V2Tabs.Tab> </V2Tabs> ``` ## Tabbable content Use the `tabbableContent` prop within the `V2Tabs.Tab` component to control the user's ability to tab-key focus the content container. `tabbableContent` is set to `true` by default. This prop is useful for addressing possible [accessibility concerns](/web/ui/tabs-v2?tab=accessibility). ```jsx live <V2Tabs> <V2Tabs.Tab tabbableContent={false} label="No Tab Key Focus"> Can't focus content with tab key </V2Tabs.Tab> <V2Tabs.Tab label="Tab Key Focus">Can focus content with tab key</V2Tabs.Tab> </V2Tabs> ``` ## Height Use the `height` property to specify the height of the container. The default is set to `null`. If height is not specified, the tab container will fit the size of the content. If height is specified, then the content becomes scrollable if the content is larger than the set height. `height` property is only applicable to `column` display. ```jsx live <Box> <Layout.Stack grow space={45}> <V2Tabs display="column" height="200px" title="Height (200px)"> <V2Tabs.Tab label="Tab 1 - 200px Height"> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum quis eros vel nibh suscipit rhoncus porta in nulla. Mauris nisl sem, semper sit amet faucibus id, lacinia cursus odio. Sed eu libero at est volutpat pulvinar eget vitae ante. Donec nec urna vehicula, fringilla nulla sit amet, laoreet justo. Phasellus accumsan ligula tempus lorem sagittis blandit. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Sed pellentesque dignissim leo in maximus. Duis ac sapien nec dolor maximus condimentum eu imperdiet urna. Nulla aliquet quam vitae massa eleifend, mattis bibendum lorem viverra. Nam interdum mi ipsum, quis congue felis pretium eu. Sed ligula augue, congue at enim id, ullamcorper gravida felis. Ut ut justo sollicitudin, pellentesque lorem ut, aliquet mi. Quisque vitae sem nulla. Praesent maximus luctus nisi, a efficitur enim pharetra a. <br /> Praesent ullamcorper nunc nec urna rutrum, sed finibus odio imperdiet. Vestibulum vel lobortis nunc. Sed facilisis augue mollis molestie faucibus. Vestibulum tincidunt faucibus dolor, vitae efficitur nibh posuere ac. Cras tortor justo, vulputate sed justo a, auctor maximus neque. Cras laoreet sodales mauris nec pulvinar. Phasellus semper elementum eros sit amet hendrerit. Ut ullamcorper porta pretium. In feugiat nisl eros, sit amet mattis lacus tincidunt ut. Cras sit amet tortor purus. Integer ac maximus arcu. Nam arcu nisl, elementum vel iaculis lobortis, mollis eget lorem. Fusce imperdiet dolor ipsum, id lacinia dui molestie id. Cras auctor erat iaculis mauris tincidunt, id dapibus tortor mollis. Nunc sagittis egestas lorem, non vehicula mauris dignissim nec. Vivamus elementum urna lacinia ante interdum, quis lobortis ligula volutpat. <br /> Nulla felis elit, faucibus in tempor eu, porttitor ac erat. Quisque a consequat nibh, nec pulvinar augue. Praesent fermentum hendrerit viverra. Aliquam sed lacinia justo. Vivamus vitae pulvinar velit. Phasellus in arcu leo. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent congue leo in mauris tincidunt, eu laoreet nulla ultricies. Mauris erat turpis, aliquam id commodo at, cursus non lorem. Maecenas imperdiet auctor nibh, at luctus mi rutrum at. Donec congue auctor dui, sit amet imperdiet ante rutrum eget. Sed lectus ipsum, feugiat sed tincidunt non, efficitur sagittis turpis. Donec pulvinar, augue at eleifend elementum, magna ante pellentesque diam, nec pretium lacus massa vel lorem. Aliquam erat volutpat. Quisque sem ipsum, ullamcorper in pharetra id, venenatis vel lectus. Fusce eros felis, porttitor eget ligula at, sollicitudin accumsan diam. </V2Tabs.Tab> <V2Tabs.Tab label="Tab 2 - 200px Height">Tab 2 Content</V2Tabs.Tab> <V2Tabs.Tab label="Tab 3 - 200px Height">Tab 3 Content</V2Tabs.Tab> </V2Tabs> <V2Tabs display="column" title="Content Height"> <V2Tabs.Tab label="Tab 1 - Content Height"> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum quis eros vel nibh suscipit rhoncus porta in nulla. Mauris nisl sem, semper sit amet faucibus id, lacinia cursus odio. Sed eu libero at est volutpat pulvinar eget vitae ante. Donec nec urna vehicula, fringilla nulla sit amet, laoreet justo. Phasellus accumsan ligula tempus lorem sagittis blandit. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Sed pellentesque dignissim leo in maximus. Duis ac sapien nec dolor maximus condimentum eu imperdiet urna. Nulla aliquet quam vitae massa eleifend, mattis bibendum lorem viverra. Nam interdum mi ipsum, quis congue felis pretium eu. Sed ligula augue, congue at enim id, ullamcorper gravida felis. Ut ut justo sollicitudin, pellentesque lorem ut, aliquet mi. Quisque vitae sem nulla. Praesent maximus luctus nisi, a efficitur enim pharetra a. <br /> Praesent ullamcorper nunc nec urna rutrum, sed finibus odio imperdiet. Vestibulum vel lobortis nunc. Sed facilisis augue mollis molestie faucibus. Vestibulum tincidunt faucibus dolor, vitae efficitur nibh posuere ac. Cras tortor justo, vulputate sed justo a, auctor maximus neque. Cras laoreet sodales mauris nec pulvinar. Phasellus semper elementum eros sit amet hendrerit. Ut ullamcorper porta pretium. In feugiat nisl eros, sit amet mattis lacus tincidunt ut. Cras sit amet tortor purus. Integer ac maximus arcu. Nam arcu nisl, elementum vel iaculis lobortis, mollis eget lorem. Fusce imperdiet dolor ipsum, id lacinia dui molestie id. Cras auctor erat iaculis mauris tincidunt, id dapibus tortor mollis. Nunc sagittis egestas lorem, non vehicula mauris dignissim nec. Vivamus elementum urna lacinia ante interdum, quis lobortis ligula volutpat. <br /> Nulla felis elit, faucibus in tempor eu, porttitor ac erat. Quisque a consequat nibh, nec pulvinar augue. Praesent fermentum hendrerit viverra. Aliquam sed lacinia justo. Vivamus vitae pulvinar velit. Phasellus in arcu leo. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent congue leo in mauris tincidunt, eu laoreet nulla ultricies. Mauris erat turpis, aliquam id commodo at, cursus non lorem. Maecenas imperdiet auctor nibh, at luctus mi rutrum at. Donec congue auctor dui, sit amet imperdiet ante rutrum eget. Sed lectus ipsum, feugiat sed tincidunt non, efficitur sagittis turpis. Donec pulvinar, augue at eleifend elementum, magna ante pellentesque diam, nec pretium lacus massa vel lorem. Aliquam erat volutpat. Quisque sem ipsum, ullamcorper in pharetra id, venenatis vel lectus. Fusce eros felis, porttitor eget ligula at, sollicitudin accumsan diam. </V2Tabs.Tab> <V2Tabs.Tab label="Tab 2 - Content Height">Tab 2 Content</V2Tabs.Tab> <V2Tabs.Tab label="Tab 3 - Content Height">Tab 3 Content</V2Tabs.Tab> </V2Tabs> </Layout.Stack> </Box> ``` ## Extra customization The `V2Tabs.Tab` component can be completely customized with the `customRender` prop. It is a function that receives the `isActive` state and allows full control over tab content rendering. Note: using `customRender` does not follow the patterns defined by our design team. We recommend developers and designers alike to follow our brand-approved design patterns when possible. ```jsx live () => { // Used to prevent shifting of component upon font weight change const TextHidden = styled(Text, { static: { visibility: 'hidden', display: 'flex', height: 0, }, dynamic: () => { const typography = useToken('typography')( '$web.semantic.typography.p.md-bold' ); return { typography, }; }, }); return ( <V2Tabs title="Extra Tabs"> <V2Tabs.Tab customRender={(isActive) => ( <Layout.Stack alignItems="center"> <IconSymbol icon={isActive ? 'check_circle' : 'circle'} /> <Text>Custom Tab 1</Text> <TextHidden>Custom Tab 1</TextHidden> </Layout.Stack> )} > Tab 1 Content with custom tab rendering </V2Tabs.Tab> <V2Tabs.Tab customRender={(isActive) => ( <Layout.Stack alignItems="center"> <IconSymbol icon={isActive ? 'check_circle' : 'circle'} /> <Text>Custom Tab 2</Text> <TextHidden>Custom Tab 2</TextHidden> </Layout.Stack> )} > Tab 2 Content with custom tab rendering </V2Tabs.Tab> <V2Tabs.Tab customRender={(isActive) => ( <Layout.Stack alignItems="center"> <IconSymbol icon={isActive ? 'check_circle' : 'circle'} /> <Text>Custom Tab 3</Text> <TextHidden>Custom Tab 3</TextHidden> </Layout.Stack> )} > Tab 3 Content with custom tab rendering </V2Tabs.Tab> </V2Tabs> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2Tabs" propTypeName="TabsProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="V2Tabs.Tab" propTypeName="ExternalTabControlProps" /> ``` ```jsx render <Docs.V2ClassesTable title="V2Tabs" classes={[TabsClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2Tabs.Tab" classes={[TabControlClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> Tabs are a set of layered sections of content, known as tab panels, that display one panel of content at a time. Each tab panel has an associated tab element that, when activated, displays the panel. The list of tab elements is arranged along one edge of the currently displayed panel, most commonly the top edge. The `title` property is used to populate the `aria-label` attribute for each Tabs component. This unique label will help distinguish one tab component from another if there are multiple tab components on the same page, which is helpful for screen reader users. Provide a name that reflects the purpose of the tabs. The `tabbableContent` property is used within `Tabs.Tab` to set the tab index of the `div` element content container. Set `false` to exclude element from tab focus. Adheres to the <ExitLink href="https://www.w3.org/TR/wai-aria-practices-1.2/#tabpanel">Tabs WAI-ARIA design pattern</ExitLink>. ```jsx live <Layout.Stack grow space={45}> <Box width={500}> <V2Tabs title="WCAG 2.2 POUR Principles"> <V2Tabs.Tab label="P - Perceivable"> <Heading display="h5">1. Perceivable</Heading> <p> Information and user interface components must be presentable to users in ways they can perceive. </p> <Heading display="h6">Guideline 1.1 Text Alternatives</Heading> <p> Provide text alternatives for any non-text content so that it can be changed into other forms people need, such as large print, braille, speech, symbols or simpler language </p> <Heading display="h6">Guideline 1.2 Time-based Media</Heading> <p>Provide alternatives for time-based media.</p> <Heading display="h6">Guideline 1.3 Adaptable</Heading> <p> Provide text alternatives for any non-text content so that it can be changed into other forms people need, such as large print, braille, speech, symbols or simpler language </p> <Heading display="h6">Guideline 1.4 Distinguishable</Heading> <p> Make it easier for users to see and hear content including separating foreground from background. </p> </V2Tabs.Tab> <V2Tabs.Tab label="O - Operable"> <Heading display="h5">2. Operable</Heading> <p>User interface components and navigation must be operable.</p> <Heading display="h6">Guideline 2.1 Keyboard Accessible</Heading> <p>Make all functionality available from a keyboard.</p> <Heading display="h6">Guideline 2.2 Enough Time</Heading> <p>Provide users enough time to read and use content.</p> <Heading display="h6"> Guideline 2.3 Seizures and Physical Reactions </Heading> <p> Do not design content in a way that is known to cause seizures or physical reactions. </p> <Heading display="h6">Guideline 2.4 Navigable</Heading> <p> Provide ways to help users navigate, find content, and determine where they are. </p> <Heading display="h6">Guideline 2.5 Input Modalities</Heading> <p> Make it easier for users to operate functionality through various inputs beyond keyboard. </p> </V2Tabs.Tab> <V2Tabs.Tab label="U - Understandable"> <Heading display="h5">3. Understandable</Heading> <Heading display="h6">Guideline 3.1 Readable</Heading> <p> Information and the operation of the user interface must be understandable. </p> <Heading display="h6">Guideline 3.2 Predictable</Heading> <p>Make Web pages appear and operate in predictable ways.</p> <Heading display="h6">Guideline 3.3 Input Assistance</Heading> <p>Help users avoid and correct mistakes.</p> </V2Tabs.Tab> <V2Tabs.Tab label="R - Robust"> <Heading display="h5">4. Robust</Heading> <p> Content must be robust enough that it can be interpreted by a wide variety of user agents, including assistive technologies. </p> <Heading display="h6">Guideline 4.1 Compatible</Heading> <p> Content must be robust enough that it can be interpreted by a wide variety of user agents, including assistive technologies. </p> </V2Tabs.Tab> </V2Tabs> </Box> <V2Tabs title="WCAG POUR Principles - Vertical" display="column" height="350px" > <V2Tabs.Tab label="Perceivable" customRender={(isActive) => { return ( <React.Fragment> <Heading offset={5} color={isActive ? '$gray8' : '$interactive1'}> P </Heading> <Text size="s">Perceivable</Text> </React.Fragment> ); }} > <Heading display="h5">1. Perceivable</Heading> <p> Information and user interface components must be presentable to users in ways they can perceive. </p> <Heading display="h6">Guideline 1.1 Text Alternatives</Heading> <p> Provide text alternatives for any non-text content so that it can be changed into other forms people need, such as large print, braille, speech, symbols or simpler language </p> <Heading display="h6">Guideline 1.2 Time-based Media</Heading> <p>Provide alternatives for time-based media.</p> <Heading display="h6">Guideline 1.3 Adaptable</Heading> <p> Provide text alternatives for any non-text content so that it can be changed into other forms people need, such as large print, braille, speech, symbols or simpler language </p> <Heading display="h6">Guideline 1.4 Distinguishable</Heading> <p> Make it easier for users to see and hear content including separating foreground from background. </p> </V2Tabs.Tab> <V2Tabs.Tab label="Operable" customRender={(isActive) => { return ( <React.Fragment> <Heading offset={5} color={isActive ? '$gray8' : '$interactive1'}> O </Heading> <Text size="s">Operable</Text> </React.Fragment> ); }} > <Heading display="h5">2. Operable</Heading> <p>User interface components and navigation must be operable.</p> <Heading display="h6">Guideline 2.1 Keyboard Accessible</Heading> <p>Make all functionality available from a keyboard.</p> <Heading display="h6">Guideline 2.2 Enough Time</Heading> <p>Provide users enough time to read and use content.</p> <Heading display="h6"> Guideline 2.3 Seizures and Physical Reactions </Heading> <p> Do not design content in a way that is known to cause seizures or physical reactions. </p> <Heading display="h6">Guideline 2.4 Navigable</Heading> <p> Provide ways to help users navigate, find content, and determine where they are. </p> <Heading display="h6">Guideline 2.5 Input Modalities</Heading> <p> Make it easier for users to operate functionality through various inputs beyond keyboard. </p> </V2Tabs.Tab> <V2Tabs.Tab label="Understandable" customRender={(isActive) => { return ( <React.Fragment> <Heading offset={5} color={isActive ? '$gray8' : '$interactive1'}> U </Heading> <Text size="s">Understandable</Text> </React.Fragment> ); }} > <Heading display="h5">3. Understandable</Heading> <Heading display="h6">Guideline 3.1 Readable</Heading> <p> Information and the operation of the user interface must be understandable. </p> <Heading display="h6">Guideline 3.2 Predictable</Heading> <p>Make Web pages appear and operate in predictable ways.</p> <Heading display="h6">Guideline 3.3 Input Assistance</Heading> <p>Help users avoid and correct mistakes.</p> </V2Tabs.Tab> <V2Tabs.Tab label="Robust" customRender={(isActive) => { return ( <React.Fragment> <Heading offset={5} color={isActive ? '$gray8' : '$interactive1'}> R </Heading> <Text size="s">Robust</Text> </React.Fragment> ); }} > <Heading display="h5">4. Robust</Heading> <p> Content must be robust enough that it can be interpreted by a wide variety of user agents, including assistive technologies. </p> <Heading display="h6">Guideline 4.1 Compatible</Heading> <p> Content must be robust enough that it can be interpreted by a wide variety of user agents, including assistive technologies. </p> </V2Tabs.Tab> </V2Tabs> </Layout.Stack> ``` ```jsx live () => { return ( <V2Tabs title="Build your bear"> <V2Tabs.Tab label="Pick your bear" subLabel="Size and breed"> We have several bears to choose from </V2Tabs.Tab> <V2Tabs.Tab label="Color" subLabel="More choices" rightAddOn={<V2Badge variant="info">Info</V2Badge>} > We now have many colors to choose from </V2Tabs.Tab> <V2Tabs.Tab label="Pay" subLabel="sub label"> We take all major credit cards </V2Tabs.Tab> </V2Tabs> ); }; ``` ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Tab', description: 'When focus moves into the tab list, places focus on the active tab element. If tab list has focus, focus moves to the tab panel. If the tab panel has focus, focus moves to the next focusable element, whether it is inside of the tab panel or outside of it.', }, { name: 'Left Arrow', description: 'When tab list is in focus, moves focus to the previous tab if the tabs are horizontal.', }, { name: 'Right Arrow', description: 'When tab list is in focus, moves focus to the next tab if the tabs are horizontal.', }, { name: 'Up Arrow', description: 'When tab list is in focus, moves focus to the previous tab if the tabs are vertical.', }, { name: 'Down Arrow', description: 'When the tab list is in focus, moves focus to the next tab if the tabs are vertical.', }, { name: 'Home', description: 'When the tab list is in focus, moves focus to the first tab.', }, { name: 'End', description: 'When the tab list is in focus, moves focus to the last tab.', }, ]} /> ``` </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={Tabs} keys={['tabsV2']} /> ``` </Tab> --- id: tabs category: Content title: Tabs description: Used to view and switch between different sets of content. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=0-1599 subDirectory: Tabs/v1 --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="Tabs"></Docs.V2MigrationBanner> ``` ```jsx import { Tabs } from '@uhg-abyss/web/ui/Tabs'; ``` ```jsx sandbox { component: 'Tabs', inputs: [ { prop: 'initialTab', type: 'number', description: 'Used to indicate initial tab', }, { prop: 'size', type: 'string', description: 'Set size of tabs', }, { prop: 'height', type: 'string', description: 'Set size of tabs', }, { prop: 'position', type: 'select', options: [ { label: 'start', value: 'start' }, { label: 'center', value: 'center' }, { label: 'end', value: 'end' }, ], }, { prop: 'variant', type: 'select', options: [ { label: 'enclosed', value: 'enclosed' }, { label: 'line', value: 'line' }, { label: 'arrow', value: 'arrow' }, ], }, { prop: 'display', type: 'select', options: [ { label: 'row', value: 'row' }, { label: 'column', value: 'column' }, ], }, { prop: 'grow', type: 'boolean', }, ] } <Tabs title="Tabs Sandbox"> <Tabs.Tab label="Tab 1">Tab 1 Content</Tabs.Tab> <Tabs.Tab label="Tab 2">Tab 2 Content</Tabs.Tab> <Tabs.Tab label="Tab 3">Tab 3 Content</Tabs.Tab> </Tabs> ``` <br /> ## Display The `display` property determines whether the tab buttons will be displayed horizontally or vertically. The two options are `row` and `column`, and the default is `row`. Additionally, the `height` property is only applicable to `column` display. ```jsx live <Card> <Card.Section> <Layout.Stack grow space={45}> <Tabs title="Display - Row"> <Tabs.Tab label="Row Display - Tab 1">Tab 1 Content</Tabs.Tab> <Tabs.Tab label="Row Display - Tab 2">Tab 2 Content</Tabs.Tab> <Tabs.Tab label="Row Display - Tab 3">Tab 3 Content</Tabs.Tab> </Tabs> <Tabs title="Display - Column" display="column"> <Tabs.Tab label="Column Display - Tab 1">Tab 1 Content</Tabs.Tab> <Tabs.Tab label="Column Display - Tab 2">Tab 2 Content</Tabs.Tab> <Tabs.Tab label="Column Display - Tab 3">Tab 3 Content</Tabs.Tab> </Tabs> </Layout.Stack> </Card.Section> </Card> ``` ## Variants Currently, there are three variants to choose from: `enclosed`, `line`, and `arrow`. Each variant can be displayed either vertically or horizontally by modifying the `display` property. The default value is `enclosed`. ```jsx live <Card> <Card.Section> <Layout.Stack grow space={45}> <Tabs title="Arrow Variant" variant="arrow"> <Tabs.Tab label="Arrow - Tab 1" /> <Tabs.Tab label="Arrow - Tab 2" /> <Tabs.Tab label="Arrow - Tab 3" /> </Tabs> <Tabs title="Enclosed Variant"> <Tabs.Tab label="Enclosed - Tab 1" /> <Tabs.Tab label="Enclosed - Tab 2" /> <Tabs.Tab label="Enclosed - Tab 3" /> </Tabs> <Tabs title="Line Variant" variant="line"> <Tabs.Tab label="Line - Tab 1" /> <Tabs.Tab label="Line - Tab 2" /> <Tabs.Tab label="Line - Tab 3" /> </Tabs> </Layout.Stack> </Card.Section> </Card> ``` ## Title The `title` property provides a label that describes the purpose of the set of tabs. This is a required property as it gives screen reader users important context. ```jsx <Tabs title="Tab Group Title"> <Tabs.Tab label="Tab - 1">Tab 1 Content</Tabs.Tab> <Tabs.Tab label="Tab - 2">Tab 2 Content</Tabs.Tab> <Tabs.Tab label="Tab - 3">Tab 3 Content</Tabs.Tab> </Tabs> ``` ## Active (controlled) To control the tabs active state pass in the index of the desired tab to the `active` prop. This must be used in combination with `onTabChange` to ensure that the active tab state is always current. If no default state is passed the active tab will default to the first tab in the sequence. ```jsx live () => { const [activeIndex, setActiveIndex] = useState(1); return ( <Layout.Stack alignItems="left" grow> <Tabs title="Active Tab" active={activeIndex} onTabChange={setActiveIndex} > <Tabs.Tab label="Tab - 1">Tab 1 Content</Tabs.Tab> <Tabs.Tab label="Tab - 2">Tab 2 Content</Tabs.Tab> <Tabs.Tab label="Tab - 3">Tab 3 Content</Tabs.Tab> </Tabs> <Layout.Group> <Button onClick={() => setActiveIndex(0)}>Set to Tab 1</Button> <Button onClick={() => setActiveIndex(1)}>Set to Tab 2</Button> <Button onClick={() => setActiveIndex(2)}>Set to Tab 3</Button> </Layout.Group> </Layout.Stack> ); }; ``` ## Initial tab (uncontrolled) If you do not need to subscribe to the tabs active state use the `initialTab` property to set the tab that is active at build time. The default is set to the first tab in the sequence. If used instead of `active` the active state will be uncontrolled and handled internally by the component. ```jsx live <Tabs initialTab={2} title="Initial Tab"> <Tabs.Tab label="Other Tab - 1">Tab 1 Content</Tabs.Tab> <Tabs.Tab label="Initial Tab - 2">Tab 2 Content</Tabs.Tab> <Tabs.Tab label="Other Tab - 3">Tab 3 Content</Tabs.Tab> </Tabs> ``` ## Tabbable content Use the `tabbableContent` prop within the `Tabs.tab` component to control the users ability to tab key focus the content container. `tabbableContent` is set to `true` by default. This prop is useful for <ExitLink href="/web/ui/tabs?tab=accessibility">Accessibility</ExitLink>, ```jsx live <Tabs> <Tabs.Tab tabbableContent={false} label="No Tab Key Focus"> Can't focus content with tab key </Tabs.Tab> <Tabs.Tab label="Tab Key Focus">Can focus content with tab key</Tabs.Tab> <Tabs.Tab tabbableContent={false} label="No Tab Key Focus"> Can't focus content with tab key </Tabs.Tab> </Tabs> ``` ## SubText Use the `subText` prop of tab to display helpful text below the tab title. ```jsx live <Card> <Card.Section> <Layout.Stack grow space={45}> <Tabs title="Enclosed Variant"> <Tabs.Tab label="Enclosed - Tab 1" subText="Sub Text" /> <Tabs.Tab label="Enclosed - Tab 2" subText="Sub Text" /> </Tabs> <Tabs title="Line Variant" variant="line"> <Tabs.Tab label="Line - Tab 1" subText={ <span style={{ display: 'inline-flex', alignItems: 'center', flexWrap: 'wrap', }} > Sub Text <IconSymbol icon="check" size={20} style={{ marginLeft: '8px' }} /> </span> } /> <Tabs.Tab label="Line - Tab 2" subText={ <span style={{ display: 'inline-flex', alignItems: 'center', flexWrap: 'wrap', }} > Sub Text <IconSymbol icon="check" size={20} style={{ marginLeft: '8px' }} /> </span> } /> </Tabs> </Layout.Stack> </Card.Section> </Card> ``` ## Grow Use the `grow` property to prevent the tabs from filling the container evenly. This allows for more customization in the structure of the tabs. ```jsx live <Card> <Card.Section> <Layout.Stack grow space={45}> <Tabs grow={false} title="Grow False - Row Display"> <Tabs.Tab label="Tab 1">Tab 1 Content</Tabs.Tab> <Tabs.Tab label="Tab 2">Tab 2 Content</Tabs.Tab> <Tabs.Tab label="Tab 3">Tab 3 Content</Tabs.Tab> </Tabs> <Tabs title="Grow True - Row Display"> <Tabs.Tab label="Tab 1">Tab 1 Content</Tabs.Tab> <Tabs.Tab label="Tab 2">Tab 2 Content</Tabs.Tab> <Tabs.Tab label="Tab 3">Tab 3 Content</Tabs.Tab> </Tabs> </Layout.Stack> </Card.Section> </Card> ``` ```jsx live <Card> <Card.Section> <Layout.Stack grow space={45}> <Tabs grow={false} height={300} title="Grow False - Row Display" display="column" > <Tabs.Tab label="Tab 1">Tab 1 Content</Tabs.Tab> <Tabs.Tab label="Tab 2">Tab 2 Content</Tabs.Tab> <Tabs.Tab label="Tab 3">Tab 3 Content</Tabs.Tab> </Tabs> <Tabs height={300} title="Grow True - Row Display" display="column"> <Tabs.Tab label="Tab 1">Tab 1 Content</Tabs.Tab> <Tabs.Tab label="Tab 2">Tab 2 Content</Tabs.Tab> <Tabs.Tab label="Tab 3">Tab 3 Content</Tabs.Tab> </Tabs> </Layout.Stack> </Card.Section> </Card> ``` ## Position Use the `position` property to organize the tabs. The three options are `start`, `center`, and `end`, and the default is set to `'start'`. Note that this only takes effect when the `grow` property is `false`. ```jsx live <Card> <Card.Section> <Layout.Stack grow space={45}> <Tabs grow={false} title="Position (Default)" variant="line"> <Tabs.Tab label="Tab 1 Default">Tab 1 Default</Tabs.Tab> <Tabs.Tab label="Tab 2 Default">Tab 2 Default</Tabs.Tab> <Tabs.Tab label="Tab 3 Default">Tab 3 Default</Tabs.Tab> </Tabs> <Tabs grow={false} position="center" title="Position (Center)" variant="line" > <Tabs.Tab label="Tab 1 Center">Tab 1 Center</Tabs.Tab> <Tabs.Tab label="Tab 2 Center">Tab 2 Center</Tabs.Tab> <Tabs.Tab label="Tab 3 Center">Tab 3 Center</Tabs.Tab> </Tabs> <Tabs grow={false} position="end" title="Position (End)" variant="line"> <Tabs.Tab label="Tab 1 End">Tab 1 End</Tabs.Tab> <Tabs.Tab label="Tab 2 End">Tab 2 End</Tabs.Tab> <Tabs.Tab label="Tab 3 End">Tab 3 End</Tabs.Tab> </Tabs> </Layout.Stack> </Card.Section> </Card> ``` ## Size Use the `size` property to specify the left and right padding of the tabs, as well as the minimum height of tabs. The default is set to `'$md'`. ```jsx live <Card> <Card.Section> <Layout.Stack grow space={45}> <Tabs grow={false} size="$sm" title="Size (Small) - Row Display"> <Tabs.Tab label="Tab 1 - Small" /> <Tabs.Tab label="Tab 2 - Small" /> <Tabs.Tab label="Tab 3 - Small" /> </Tabs> <Tabs grow={false} title="Size (Default) - Row Display"> <Tabs.Tab label="Tab 1 - Default" /> <Tabs.Tab label="Tab 2 - Default" /> <Tabs.Tab label="Tab 3 - Default" /> </Tabs> <Tabs grow={false} size="$lg" title="Size (Large) - Row Display"> <Tabs.Tab label="Tab 1 - Large" /> <Tabs.Tab label="Tab 2 - Large" /> <Tabs.Tab label="Tab 3 - Large" /> </Tabs> </Layout.Stack> </Card.Section> </Card> ``` ```jsx live <Card> <Card.Section> <Layout.Stack grow space={45}> <Tabs grow={false} title="Size (Default) - Column Display" variant="arrow" display="column" > <Tabs.Tab label="Tab 1 - Default">Tab 1 Content</Tabs.Tab> <Tabs.Tab label="Tab 2 - Default">Tab 2 Content</Tabs.Tab> <Tabs.Tab label="Tab 3 - Default">Tab 3 Center</Tabs.Tab> </Tabs> <Tabs grow={false} size="$sm" title="Size (Small) - Column Display" variant="arrow" display="column" > <Tabs.Tab label="Tab 1 - Small">Tab 1 Content</Tabs.Tab> <Tabs.Tab label="Tab 2 - Small">Tab 2 Content</Tabs.Tab> <Tabs.Tab label="Tab 3 - Small">Tab 3 Content</Tabs.Tab> </Tabs> <Tabs grow={false} size="$lg" title="Size (Large) - Column Display" variant="arrow" display="column" > <Tabs.Tab label="Tab 1 - Large">Tab 1 Content</Tabs.Tab> <Tabs.Tab label="Tab 2 - Large">Tab 2 Content</Tabs.Tab> <Tabs.Tab label="Tab 3 - Large">Tab 3 Content</Tabs.Tab> </Tabs> </Layout.Stack> </Card.Section> </Card> ``` ## Height Use the `height` property to specify the height of the container. The default is set to `null`. If height is not specified, the tab container will fit the size of the content. If height is specified, then the content becomes scrollable if the content is larger than the set height. `height` property is only applicable to `column` display. ```jsx live <Card> <Card.Section> <Layout.Stack grow space={45}> <Tabs display="column" variant="arrow" height="200px" title="Height (200px)" > <Tabs.Tab label="Tab 1 - 200px Height"> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum quis eros vel nibh suscipit rhoncus porta in nulla. Mauris nisl sem, semper sit amet faucibus id, lacinia cursus odio. Sed eu libero at est volutpat pulvinar eget vitae ante. Donec nec urna vehicula, fringilla nulla sit amet, laoreet justo. Phasellus accumsan ligula tempus lorem sagittis blandit. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Sed pellentesque dignissim leo in maximus. Duis ac sapien nec dolor maximus condimentum eu imperdiet urna. Nulla aliquet quam vitae massa eleifend, mattis bibendum lorem viverra. Nam interdum mi ipsum, quis congue felis pretium eu. Sed ligula augue, congue at enim id, ullamcorper gravida felis. Ut ut justo sollicitudin, pellentesque lorem ut, aliquet mi. Quisque vitae sem nulla. Praesent maximus luctus nisi, a efficitur enim pharetra a. <br /> Praesent ullamcorper nunc nec urna rutrum, sed finibus odio imperdiet. Vestibulum vel lobortis nunc. Sed facilisis augue mollis molestie faucibus. Vestibulum tincidunt faucibus dolor, vitae efficitur nibh posuere ac. Cras tortor justo, vulputate sed justo a, auctor maximus neque. Cras laoreet sodales mauris nec pulvinar. Phasellus semper elementum eros sit amet hendrerit. Ut ullamcorper porta pretium. In feugiat nisl eros, sit amet mattis lacus tincidunt ut. Cras sit amet tortor purus. Integer ac maximus arcu. Nam arcu nisl, elementum vel iaculis lobortis, mollis eget lorem. Fusce imperdiet dolor ipsum, id lacinia dui molestie id. Cras auctor erat iaculis mauris tincidunt, id dapibus tortor mollis. Nunc sagittis egestas lorem, non vehicula mauris dignissim nec. Vivamus elementum urna lacinia ante interdum, quis lobortis ligula volutpat. <br /> Nulla felis elit, faucibus in tempor eu, porttitor ac erat. Quisque a consequat nibh, nec pulvinar augue. Praesent fermentum hendrerit viverra. Aliquam sed lacinia justo. Vivamus vitae pulvinar velit. Phasellus in arcu leo. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent congue leo in mauris tincidunt, eu laoreet nulla ultricies. Mauris erat turpis, aliquam id commodo at, cursus non lorem. Maecenas imperdiet auctor nibh, at luctus mi rutrum at. Donec congue auctor dui, sit amet imperdiet ante rutrum eget. Sed lectus ipsum, feugiat sed tincidunt non, efficitur sagittis turpis. Donec pulvinar, augue at eleifend elementum, magna ante pellentesque diam, nec pretium lacus massa vel lorem. Aliquam erat volutpat. Quisque sem ipsum, ullamcorper in pharetra id, venenatis vel lectus. Fusce eros felis, porttitor eget ligula at, sollicitudin accumsan diam. </Tabs.Tab> <Tabs.Tab label="Tab 2 - 200px Height">Tab 2 Content</Tabs.Tab> <Tabs.Tab label="Tab 3 - 200px Height">Tab 3 Content</Tabs.Tab> </Tabs> <Tabs display="column" variant="arrow" grow={false} title="Content Height" > <Tabs.Tab label="Tab 1 - Content Height"> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum quis eros vel nibh suscipit rhoncus porta in nulla. Mauris nisl sem, semper sit amet faucibus id, lacinia cursus odio. Sed eu libero at est volutpat pulvinar eget vitae ante. Donec nec urna vehicula, fringilla nulla sit amet, laoreet justo. Phasellus accumsan ligula tempus lorem sagittis blandit. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Sed pellentesque dignissim leo in maximus. Duis ac sapien nec dolor maximus condimentum eu imperdiet urna. Nulla aliquet quam vitae massa eleifend, mattis bibendum lorem viverra. Nam interdum mi ipsum, quis congue felis pretium eu. Sed ligula augue, congue at enim id, ullamcorper gravida felis. Ut ut justo sollicitudin, pellentesque lorem ut, aliquet mi. Quisque vitae sem nulla. Praesent maximus luctus nisi, a efficitur enim pharetra a. <br /> Praesent ullamcorper nunc nec urna rutrum, sed finibus odio imperdiet. Vestibulum vel lobortis nunc. Sed facilisis augue mollis molestie faucibus. Vestibulum tincidunt faucibus dolor, vitae efficitur nibh posuere ac. Cras tortor justo, vulputate sed justo a, auctor maximus neque. Cras laoreet sodales mauris nec pulvinar. Phasellus semper elementum eros sit amet hendrerit. Ut ullamcorper porta pretium. In feugiat nisl eros, sit amet mattis lacus tincidunt ut. Cras sit amet tortor purus. Integer ac maximus arcu. Nam arcu nisl, elementum vel iaculis lobortis, mollis eget lorem. Fusce imperdiet dolor ipsum, id lacinia dui molestie id. Cras auctor erat iaculis mauris tincidunt, id dapibus tortor mollis. Nunc sagittis egestas lorem, non vehicula mauris dignissim nec. Vivamus elementum urna lacinia ante interdum, quis lobortis ligula volutpat. <br /> Nulla felis elit, faucibus in tempor eu, porttitor ac erat. Quisque a consequat nibh, nec pulvinar augue. Praesent fermentum hendrerit viverra. Aliquam sed lacinia justo. Vivamus vitae pulvinar velit. Phasellus in arcu leo. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent congue leo in mauris tincidunt, eu laoreet nulla ultricies. Mauris erat turpis, aliquam id commodo at, cursus non lorem. Maecenas imperdiet auctor nibh, at luctus mi rutrum at. Donec congue auctor dui, sit amet imperdiet ante rutrum eget. Sed lectus ipsum, feugiat sed tincidunt non, efficitur sagittis turpis. Donec pulvinar, augue at eleifend elementum, magna ante pellentesque diam, nec pretium lacus massa vel lorem. Aliquam erat volutpat. Quisque sem ipsum, ullamcorper in pharetra id, venenatis vel lectus. Fusce eros felis, porttitor eget ligula at, sollicitudin accumsan diam. </Tabs.Tab> <Tabs.Tab label="Tab 2 - Content Height">Tab 2 Content</Tabs.Tab> <Tabs.Tab label="Tab 3 - Content Height">Tab 3 Content</Tabs.Tab> </Tabs> </Layout.Stack> </Card.Section> </Card> ``` ## Custom headers Use the `customRender` prop to create custom headers with ability to differentiate between Active and Inactive tabs. ```jsx live <Tabs grow title="Custom Headers 1"> <Tabs.Tab customRender={(isActive) => { return ( <React.Fragment> <Heading offset={5} color={isActive ? '$gray8' : '$interactive1'}> Manage 3rd Party Requests </Heading> <Text size="xs"> View and edit 3rd party access to your organization </Text> </React.Fragment> ); }} > Tab 1 Content </Tabs.Tab> <Tabs.Tab customRender={(isActive) => { return ( <React.Fragment> <Heading offset={5} color={isActive ? '$gray8' : '$interactive1'}> Request 3rd Party Access </Heading> <Text size="xs"> Submit Access Requests to 3rd Party Organizations </Text> </React.Fragment> ); }} > Tab 2 Content </Tabs.Tab> </Tabs> ``` ```jsx live () => { const content = `Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.`; const src = utils.useBaseUrl('img/graphics/carousel/pillsMd.png'); const slides = Array.from(Array(2).keys()).map((i) => { return ( <Slide height="300px" compact variant="white"> <Slide.Container> <Slide.Title>Title {i + 1}</Slide.Title> <Slide.Content>{content}</Slide.Content> <Slide.Button href="https://www.google.com">Primary</Slide.Button> </Slide.Container> </Slide> ); }); return ( <Tabs display="column" size="$md" variant="arrow" title="Custom Headers 2"> <Tabs.Tab customRender={(isActive) => { return ( <React.Fragment> <Flex justify="center" alignItems="center"> <IconBrand icon="chat" size={24} style={{ marginRight: '8px' }} /> <Flex direction="column"> <Heading size="20px" offset={5} color={isActive ? '$gray8' : '$interactive1'} > Sample Tab 1 </Heading> <Text size="12px" color={isActive ? '$gray8' : '$gray7'} style={{ textAlign: 'left', fontWeight: 'normal' }} > {isActive ? 'ACTIVE' : 'INACTIVE'} </Text> </Flex> </Flex> </React.Fragment> ); }} > <div style={{ display: 'flex', justifyContent: 'end' }}> <Carousel compact slides={slides} variant="white" /> </div> </Tabs.Tab> <Tabs.Tab customRender={(isActive) => { return ( <React.Fragment> <Flex justify="center" alignItems="center"> <IconBrand icon="chat" size={24} style={{ marginRight: '8px' }} /> <Flex direction="column"> <Heading size="20px" offset={5} color={isActive ? '$gray8' : '$interactive1'} > Sample Tab 2 </Heading> <Text size="12px" color={isActive ? '$gray8' : '$gray7'} style={{ textAlign: 'left', fontWeight: 'normal' }} > {isActive ? 'ACTIVE' : 'INACTIVE'} </Text> </Flex> </Flex> </React.Fragment> ); }} > <div style={{ display: 'flex', justifyContent: 'end' }}> <Carousel compact slides={slides} variant="white" /> </div> </Tabs.Tab> <Tabs.Tab customRender={(isActive) => { return ( <React.Fragment> <Flex justify="center" alignItems="center"> <IconBrand icon="chat" size={24} style={{ marginRight: '8px' }} /> <Flex direction="column"> <Heading size="20px" offset={5} color={isActive ? '$gray8' : '$interactive1'} > Sample Tab 3 </Heading> <Text size="12px" color={isActive ? '$gray8' : '$gray7'} style={{ textAlign: 'left', fontWeight: 'normal' }} > {isActive ? 'ACTIVE' : 'INACTIVE'} </Text> </Flex> </Flex> </React.Fragment> ); }} > <div style={{ display: 'flex', justifyContent: 'end' }}> <Carousel compact slides={slides} variant="white" /> </div> </Tabs.Tab> </Tabs> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={Tabs} rows={[ { name: 'children', type: 'ReactNode', description: 'The individual tabs and their content', }, { name: 'title', type: 'string', description: 'The name for the tab container. Used to set the aria-label tag for accessibility concerns.', }, { name: 'initialTab', type: 'number', description: 'Used to indicate initial tab', }, { name: 'active', type: 'number', description: 'Used to control state and set active tab', }, { name: 'position', type: "'start' | 'center' | 'end'", description: 'Set position of tab', }, { name: 'grow', type: 'boolean', description: 'Flag to grow tabs evenly among space provided', }, { name: 'onTabChange', type: 'function', description: 'Callback fired every time tab changes; returns index of selected tab', }, { name: 'display', type: "'row' | 'column'", description: 'Set the orientation of the tabs', }, { name: 'variant', type: "'enclosed' | 'line' | 'arrow'", description: 'Set variant of tab between enclosed, line, or arrow', }, { name: 'tabsListProps', type: 'shape', description: 'Props to be passed to tabs list', }, { name: 'size', type: 'number | string', description: 'Set size of tabs', }, { name: 'height', type: 'number | string', description: 'Set height of container', }, { name: 'sizes', type: 'shape', description: 'Default size options of tabs', }, ]} /> ``` ```jsx render <Docs.PropsTable of={Tabs.Tab} rows={[ { name: 'children', type: 'ReactNode', description: 'The contents of the tab', }, { name: 'label', type: 'string | node', description: 'The label of the tab', }, { name: 'customRender', type: 'function', description: 'Custom render for tab content. Callback returns the active state of the tab.', }, { name: 'subText', type: 'string | node', description: 'Sub Text of the tab.', }, { name: 'tabbableContent', type: 'boolean', default: 'true', description: `Sets tab index for content div. Defaults to true. More details available on Accessibility tab.`, }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Tabs} rows={[ { name: 'tabs-root', description: 'Tabs root element', }, { name: 'tabs-list', description: 'List of tabs', }, { name: 'tabs-content-container', description: 'Container of content in tab', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Tabs.Tab} rows={[ { name: 'tabs-tab', description: 'Tabs.Tab root element', }, { name: 'Line indicating the active tab', description: 'Line indicating the active tab', }, { name: 'tabs-tab-content', description: 'Container of content in tab for label / custom rendering', }, { name: 'tabs-tab-subtext', description: 'Subtext of the tab', }, ]} /> ``` </Tab> <Tab label="Accessibility"> Tabs are a set of layered sections of content, known as tab panels, that display one panel of content at a time. Each tab panel has an associated tab element, that when activated, displays the panel. The list of tab elements is arranged along one edge of the currently displayed panel, most commonly the top edge. The `title` property is used to populate the `aria-label` attribute for each Tabs component. This unique label will help distinguish one tab component from another if there are multiple tab components on the same page, which is helpful for screen reader users. Provide a name that reflects the purpose of the tabs. The `tabbableContent` property is used within `Tabs.Tab` to set the tab index of the `div` element content container. Set `false` to exclude element from tab focus. Adheres to the <ExitLink href="https://www.w3.org/TR/wai-aria-practices-1.2/#tabpanel">Tabs WAI-ARIA design pattern</ExitLink>. ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Tab', description: 'When focus moves into the tab list, places focus on the active tab element. If tab list has focus, focus moves to the tab panel. If the tab panel has focus, focus moves to the next focusable element, whether it is inside of the tab panel or outside of it.', }, { name: 'Left Arrow', description: 'When tab list is in focus, moves focus to the previous tab if the tabs are horizontal.', }, { name: 'Right Arrow', description: 'When tab list is in focus, moves focus to the next tab if the tabs are horizontal.', }, { name: 'Up Arrow', description: 'When tab list is in focus, moves focus to the previous tab if the tabs are vertical.', }, { name: 'Down Arrow', description: 'When the tab list is in focus, moves focus to the next tab if the tabs are vertical.', }, { name: 'Home', description: 'When the tab list is in focus, moves focus to the first tab.', }, { name: 'End', description: 'When the tab list is in focus, moves focus to the last tab.', }, ]} /> ``` </Tab> --- id: text-v2 category: Typography title: V2Text description: Used to apply Abyss typography styles to text elements subDirectory: Text/v2 sourceIsTS: true --- <Tab label="Overview"> ```jsx import { V2Text } from '@uhg-abyss/web/ui/Text'; ``` ```jsx sandbox { component: 'V2Text', inputs: [ { prop: 'children', type: 'string', }, { prop: 'color', type: 'string', }, { prop: 'fontWeight', type: 'select', options: [ { label: 'regular', value: 'regular' }, { label: 'medium', value: 'medium' }, { label: 'bold', value: 'bold' }, ], }, { prop: 'fontSize', type: 'select', options: [ { label: 'xs', value: 'xs' }, { label: 'sm', value: 'sm' }, { label: 'md', value: 'md' }, { label: 'lg', value: 'lg' }, ], }, ], } <V2Text color="$web.semantic.color.text.content.secondary" fontSize="md" fontWeight="regular" > Lorem ipsum dolor sit amet. </V2Text> ``` ## Color Use the `color` prop to set the color of the text. This prop accepts any valid <ExitLink href="https://developer.mozilla.org/en-US/docs/Web/CSS/color">CSS color identifier</ExitLink> (RGB, HSL, named color, etc.) as well as <BrandLink category="colors-v2">Abyss color tokens</BrandLink>. The default value is `'$web.semantic.color.text.content.secondary'`. Note: Text colors _must_ meet the minimum 4.5:1 contrast ratio for normal text and 3:1 for large text as per <ExitLink href="https://www.w3.org/TR/WCAG21/#contrast-minimum">WCAG 2.1 guidelines</ExitLink>. ```jsx live <Layout.Stack alignItems="left"> <V2Text>Lorem ipsum dolor sit amet. (Default)</V2Text> <V2Text color="$web.semantic.color.text.status.error"> Lorem ipsum dolor sit amet. (Token) </V2Text> <V2Text color="#821BB6">Lorem ipsum dolor sit amet. (Hex)</V2Text> <V2Text color="blue">Lorem ipsum dolor sit amet. (Named color)</V2Text> </Layout.Stack> ``` ## Font size Use the `fontSize` prop to change the size of the text. The available options are `'lg'`, `'md'`, `'sm'`, and `'xs'`. The default value is `'md'`. ```jsx live <Layout.Stack alignItems="left"> <V2Text fontSize="lg">Large (18px)</V2Text> <V2Text fontSize="md">Medium (16px)</V2Text> <V2Text fontSize="sm">Small (14px)</V2Text> <V2Text fontSize="xs">Extra Small (12px)</V2Text> </Layout.Stack> ``` ## Font weight Use the `fontWeight` prop to change the weight of the text. The available options are `'bold'`, `'medium'`, and `'regular'`. The default value is `'regular'`. ```jsx live <Layout.Stack alignItems="left"> <V2Text fontWeight="bold">Bold</V2Text> <V2Text fontWeight="medium">Medium</V2Text> <V2Text fontWeight="regular">Regular</V2Text> </Layout.Stack> ``` ## Polymorphic component The `V2Text` component is polymorphic, meaning that the underlying HTML element can be changed using the `as` prop. By default, the component renders as a `<span>`. ```jsx live <Layout.Stack alignItems="left"> <V2Text>Lorem ipsum dolor sit amet. (Span)</V2Text> <V2Text as="p">Lorem ipsum dolor sit amet. (Paragraph)</V2Text> <V2Text as="div">Lorem ipsum dolor sit amet. (Div)</V2Text> </Layout.Stack> ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2Text" propTypeName="TextProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2ClassesTable title="V2Text" classes={[V2TextClassesMetadata]} /> ``` </Tab> --- id: text category: Typography title: Text description: Used to create segments of text such as phrases, sentences, and paragraphs. design: https://www.figma.com/file/tk08Md4NBBVUPNHQYthmqp/Abyss-Design-System?node-id=0%3A367 pagination_next: null --- <Tab label="Overview"> ```jsx import { Text } from '@uhg-abyss/web/ui/Text'; ``` ```jsx sandbox { component: 'Text', inputs: [ { prop: 'children', type: 'string', }, { prop: 'color', type: 'string', }, { prop: 'fontWeight', type: 'string', }, { prop: 'size', type: 'string', }, { prop: 'transform', type: 'select', options: [ { label: 'default', value: null }, { label: 'capitalize', value: 'capitalize' }, { label: 'lowercase', value: 'lowercase' }, { label: 'uppercase', value: 'uppercase' }, ], }, ], } <Text>Enter message here</Text> ``` ## Color Use the `color` property to set the color of the text. The default is set to `black`. When choosing colors they must be checked for compliance under the WCAG 2.1 guidelines. Refer to the <BrandLink category="colors">Accessibility Section in Colors</BrandLink> for more details. ```jsx live <Layout.Stack alignItems="left"> <Text>Some filler text - Black</Text> <Text color="$error1">Some filler text - error</Text> <Text color="#5C005C">Some filler text - hex</Text> <Text color="blue">Some filler text - color</Text> </Layout.Stack> ``` ## Sizes Use the `size` property to change the size of the text. The default is set to md which is 16px. The values for each size are represented by `FontSize - LineHeight`. ```jsx live <Layout.Stack alignItems="left"> <Text size="$lg">Body 1 - Large / 18px - 24px</Text> <Text size="$md">Body 2 - Medium / 16px - 20px</Text> <Text size="$sm">Body 3 - Small / 14px - 18px</Text> <Text size="$xs">Small 1 - Extra Small / 12px - 16px</Text> </Layout.Stack> ``` ## Transform Use the `transform` property to change the formatting of the text. Variants available include the default case, `capitalize` the first letter of each word, `lowercase` all letters, or `uppercase` all letters. ```jsx live <Layout.Stack alignItems="left"> <Text>Default text</Text> <Text transform="capitalize">Capitalize text</Text> <Text transform="lowercase">Lowercase text</Text> <Text transform="uppercase">Uppercase text</Text> </Layout.Stack> ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={Text} rows={[ { name: 'children', type: 'string', description: 'The contents of the text component', }, { name: 'color', type: 'string', description: 'Set the color of the text', }, { name: 'size', type: 'number | string', description: 'Set the size of the text', }, { name: 'sizes', type: 'object', description: 'Default size options for text', }, { name: 'transform', type: 'string', description: 'Reformat the text by changing whether letters are capitalized or not', }, { name: 'fontWeight', type: 'number | string', description: 'Set the font weight of text', }, { name: 'lineHeights', type: 'object', description: 'Default line height options for text', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Text} rows={[ { name: 'text-root', description: 'Text root element', }, ]} /> ``` </Tab> --- id: text-input-v2 category: Forms title: V2TextInput description: Allows users to enter text into a UI. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=10515-5846 subDirectory: TextInput/v2 sourceIsTS: true --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="TextInput"></Docs.V2MigrationBanner> ``` ```jsx import { V2TextInput } from '@uhg-abyss/web/ui/TextInput'; ``` ```jsx sandbox { component: 'V2TextInput', inputs: [ { prop: 'subText', type: 'string', defaultValue: 'Subtext', }, { prop: 'width', type: 'string', }, { prop: 'prefix', type: 'string', }, { prop: 'suffix', type: 'string', }, { prop: 'mask', type: 'select', isClearable: true, options: [ { label: 'Phone', value: 'phone' }, { label: 'SSN', value: 'ssn' }, { label: 'Date', value: 'date' }, { label: 'Zipcode', value: 'zip' }, { label: 'Numeric', value: 'numeric' }, ] }, { prop: 'type', type: 'select', isClearable: true, options: [ { label: 'Text', value: 'text' }, { label: 'Password', value: 'password' }, ] }, { prop: 'hideLabel', type: 'boolean', }, { prop: 'isClearable', type: 'boolean', }, { prop: 'isDisabled', type: 'boolean', }, { prop: 'highlighted', type: 'boolean', defaultValue: false, }, ] } () => { const [value, setValue] = useState(''); return ( <V2TextInput label="TextInput Sandbox" value={value} isClearable onChange={(e) => setValue(e.target.value)} /> ); }; ``` ## Form integration ### useFormV2 (recommended) ```jsx render <Docs.FormMessage /> ``` <br /> ```jsx render <Docs.FormDisclaimer /> ``` <br /> ```jsx live () => { const form = useFormV2({ defaultValues: { textForm: 'init', }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2TextInput label="TextInput Form" model="textForm" isClearable validators={{ required: true }} /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ### useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [value, setValue] = useState(''); const onSubmit = () => { console.log('value', value); }; return ( <React.Fragment> <V2TextInput label="TextInput useState" value={value} isClearable onChange={(e) => setValue(e.target.value)} /> <V2Button onClick={onSubmit} css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </React.Fragment> ); }; ``` ## Display properties ### Label Use the `label` prop to display a label above the input. To hide the input label, set `hideLabel` to `true`. Use `isRequired` and `isOptional` for further customization. Note: If using `useForm`, do not use `isRequired`. The same functionality can be achieved with `required: true` in `validators`. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', flexGrow: 0, }), [] ); const form = useFormV2(); return ( <V2FormProvider state={form}> <FormSpacing> <V2TextInput label="Custom Label" model="custom-label" /> <V2TextInput label="Hidden Label" model="custom-hidden-label" hideLabel /> <V2TextInput label="Required Label" model="custom-req-label" isRequired /> <V2TextInput label="Optional Label" model="custom-opt-label" isOptional /> </FormSpacing> </V2FormProvider> ); }; ``` ### Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip-v2) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip-v2) or a [Popover](/web/ui/popover-v2). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip-v2/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); return ( <V2FormProvider state={form}> <FormSpacing> <V2TextInput label="Default Helper" helper="This is a tooltip" model="helper-tooltip" /> <V2TextInput label="Custom Helper" helper={ <V2Popover title="Custom Helper" content="This is a popover" /> } model="helper-custom" validators={{ required: true }} /> </FormSpacing> </V2FormProvider> ); }; ``` ### Prefix and suffix Use the `prefix` and `suffix` props to display helpful text within the input field. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); return ( <V2FormProvider state={form}> <FormSpacing> <V2TextInput label="Prefix" model="prefix" prefix="$" /> <V2TextInput label="Suffix" model="suffix" suffix="lbs" /> <V2TextInput label="Prefix and Suffix" model="both" prefix="$" suffix="USD" /> </FormSpacing> </V2FormProvider> ); }; ``` ### Subtext Use the `subText` prop to display helpful information related to the input field. The prop accepts either a string or an object of the form: ```ts { text: string; position: 'above' | 'below'; } ``` The `position` property determines where the subtext will be displayed in relation to the input field. The default value is `'below'`. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); return ( <V2FormProvider state={form}> <FormSpacing> <V2TextInput label="Regular Sub Text" model="subText" subText="Subtext with a regular string" /> <V2TextInput label="Sub Text passed as an object" model="subText" subText={{ text: 'Subtext passed above the input', position: 'above', }} /> <V2TextInput label="Sub Text passed as an object" model="subText" subText={{ text: 'Subtext passed below the input', position: 'below', }} /> </FormSpacing> </V2FormProvider> ); }; ``` ### Width Use the `width` prop to set the width of the input field. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); return ( <V2FormProvider state={form}> <FormSpacing> <V2TextInput label="Width Default" model="width1" isClearable /> <V2TextInput width="75%" label="Width 75%" model="width2" isClearable /> <V2TextInput width="335px" model="width3" label="Width 335px" isClearable /> </FormSpacing> </V2FormProvider> ); }; ``` ### Left element Use the `inputLeftElement` prop to add an element inside of the text input field. The recommended usage is for inserting icons. The prop accepts an object with the following properties: - `element`: The element to be displayed inside the input field. - `description`: An optional string that describes the purpose of the element for screen readers. These are considered decorative and do not need to be exposed to screen readers. That said, please note that icons should _not_ provide any information that is not also conveyed in a screen-readable way. For example, an exclamation mark (!) icon to indicate errors needs to be accompanied by `aria-invalid`. If the icon is used to convey additional information, use the `inputLeftElement.description` prop to provide a description for screen readers. ```jsx live () => { const form = useFormV2({ defaultValues: { leftElement: '1123123.12', }, }); const onSubmit = (data) => { console.log(data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2TextInput label="Left Element" model="leftElement" isClearable mask="numeric" inputLeftElement={{ element: ( <IconSymbol icon="account_balance" size="$web.semantic.sizing.icon.utility.sm" color="$input-v2.color.icon.content" /> ), description: 'Account Balance', }} maskConfig={{ thousandSeparator: ',', decimalScale: 2, }} /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ### Add-ons Use the `leftAddOn` and `rightAddOn` props to add add-ons to the outside of the text input field. The recommended usage is for inserting supplemental text. It is recommended to use the `leftAddOnDescription` and `rightAddOnDescription` props to communicate the purpose of the add-ons to screen reader users. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); return ( <V2FormProvider state={form}> <FormSpacing> <V2TextInput label="Left Addons" model="leftAddOn" isClearable leftAddOn="http://" leftAddOnDescription="URL Prefix" /> <V2TextInput label="Right Addons" model="rightAddOn" isClearable leftAddOn="http://" rightAddOn=".com" leftAddOnDescription="URL Prefix" rightAddOnDescription="URL Suffix" /> </FormSpacing> </V2FormProvider> ); }; ``` ## Validation ### Validators (useFormV2) ```jsx render <Docs.FormCompatibilityWidget useForm /> ``` Use the `validators` prop to set validation rules for the field when using `useFormV2`. See the examples below for implementation on various types of validation. Note: The default error message when `required` is `true` is minimally acceptable for accessibility. It is highly recommended to customize it to be more specific to the use of the field and form. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); return ( <V2FormProvider state={form}> <FormSpacing> <V2TextInput label="Required Default Message" model="required" validators={{ required: true }} /> <V2TextInput label="Required Custom Message" model="custom-required" validators={{ required: 'Custom Error Message' }} /> <V2TextInput label="Min Length" model="minLength" validators={{ required: true, minLength: { value: 4, message: 'Min Length 4', }, }} /> <V2TextInput label="Max Length" model="maxLength" validators={{ required: true, maxLength: { value: 4, message: 'Max Length 4', }, }} /> <V2TextInput label="Custom Pattern (Email)" model="pattern" autoComplete="email" validators={{ required: true, pattern: { value: /^(([^<>()[\]\\.,;:\s@\"]+(\.[^<>()[\]\\.,;:\s@\"]+))|(\".+\"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/, message: 'Invalid Email', }, }} /> <V2TextInput label="Custom Validators" model="validate" validators={{ validate: { positive: (v) => parseInt(v) > 0 || 'should be greater than 0', lessThanTen: (v) => parseInt(v) < 10 || 'should be lower than 10', // you can do asynchronous validation as well // checkUrl: async () => await fetch() || 'error message', // messages: (v) => !v && ['otherInput1', 'otherInput2'], }, }} /> </FormSpacing> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ### Error message (useState) ```jsx render <Docs.FormCompatibilityWidget useState /> ``` Use the `errorMessage` prop to display a custom error message below the input field when using `useState`. ```jsx live () => { const [value, setValue] = useState('State Default Value'); return ( <V2TextInput label="Error Message" value={value} onChange={(e) => setValue(e.target.value)} errorMessage="Custom Error Message" /> ); }; ``` ### Success message ```jsx render <Docs.FormCompatibilityWidget useForm useState /> ``` Use the `successMessage` prop to display a custom success message below the input field. To provide a single success message across all form input components using `useFormV2`/`V2FormProvider`, you can provide `successMessage` to `V2FormProvider` as shown [here](/web/ui/form-provider-v2#successmessage). ```jsx live () => { const form = useFormV2(); const onSubmit = (data) => { // Do something on submit console.log(data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2TextInput data-testid="email" label="Email Address (useForm)" model="email" successMessage="Email is valid" validators={{ required: 'Email is required', pattern: { value: /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,4}$/i, message: 'Invalid email address', }, }} /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ```jsx live () => { const inputRef = useRef(null); const [email, setEmail] = useState(''); const [isSubmitted, setIsSubmitted] = useState(false); const [errorMessage, setErrorMessage] = useState(''); const [successMessage, setSuccessMessage] = useState(''); const validateEmail = () => { const emailIsValid = /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,4}$/i.test( email ); if (!emailIsValid) { setSuccessMessage(''); setErrorMessage('Invalid email address'); inputRef.current.focus(); return; } else { setErrorMessage(''); setSuccessMessage('Email is valid!'); } }; useEffect(() => { if (isSubmitted) { validateEmail(); } }, [email]); const onSubmit = (event) => { event.preventDefault(); validateEmail(); setIsSubmitted(true); }; return ( <form onSubmit={onSubmit}> <V2TextInput data-testid="email" label="Email Address (useState)" value={email} onChange={(e) => setEmail(e.target.value)} ref={inputRef} successMessage={successMessage} errorMessage={errorMessage} /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </form> ); }; ``` ### Highlighted ```jsx render <Docs.FormCompatibilityWidget useForm useState /> ``` Use the `highlighted` prop to enable a distinct background color when fields are required. To supply this across all form input components using `useFormV2`/`V2FormProvider` you can provide `highlighted` to `V2FormProvider` as shown [here](/web/ui/form-provider-v2#highlighted). ```jsx live () => { const [value, setValue] = useState(''); return ( <V2TextInput label="Highlighted useState" value={value} isClearable onChange={(e) => setValue(e.target.value)} isRequired highlighted /> ); }; ``` ```jsx live () => { const form = useFormV2(); return ( <V2FormProvider state={form}> <V2TextInput label="Highlighted useForm" model="textForm" isClearable validators={{ required: true }} highlighted /> </V2FormProvider> ); }; ``` ## Interactivity ### Clearable Set the `isClearable` prop to `true` to display a clear button in the input field. The optional `onClear` callback prop can be used to trigger additional actions when the clear button is clicked. ```jsx live () => { const form = useFormV2({ defaultValues: { clearable: 'Clearable', }, }); return ( <V2FormProvider state={form}> <V2TextInput label="Clearable" model="clearable" isClearable={true} onClear={() => console.log('input cleared')} /> </V2FormProvider> ); }; ``` ### Disabled Set the `isDisabled` prop to `true` to disable the input field, so users cannot enter a value. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2({ defaultValues: { disabled: 'Disabled', }, }); return ( <V2FormProvider state={form}> <FormSpacing> <V2TextInput isDisabled={true} label="Disabled" model="disabled" /> <V2TextInput isDisabled={true} label="Addons with Disabled" model="disabled" leftAddOn={ <Text color="$gray8" size="$md"> http:// </Text> } rightAddOn={ <Text color="$gray8" size="$md"> .com </Text> } /> </FormSpacing> </V2FormProvider> ); }; ``` ### Max length Use the `maxLength` prop to limit the number of characters allowed in the input field. Note: Default values created in `useFormV2()` can be longer than `maxLength`. It currently only applies to inputted values after initial load. ```jsx live () => { const form = useFormV2(); return ( <V2FormProvider state={form}> <V2TextInput label="Max Length" maxLength={4} model="maxLength" /> </V2FormProvider> ); }; ``` ### Auto complete Use the `autoComplete` prop whenever you are collecting information about the user. Head to <ExitLink href="https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete">Mozilla</ExitLink> to find all of the autocomplete options. ```jsx live () => { const form = useFormV2(); return ( <V2FormProvider state={form}> <V2TextInput label="Phone Number Auto Complete" mask="phone" model="autocomplete" autoComplete="tel-local" /> </V2FormProvider> ); }; ``` ### Formatter Use the `formatter` prop to format values on change for text inputs. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); return ( <V2FormProvider state={form}> <FormSpacing> <V2TextInput label="Replace special characters with empty string" model="replaceSpecialCharacters" formatter={(value) => { return value.replace(/[&\/\\#,+()$~%.'":?<>{}]/g, ''); }} /> <V2TextInput label="Uppercase Characters" model="uppercase" formatter={(value) => { return value.toUpperCase(); }} /> </FormSpacing> </V2FormProvider> ); }; ``` ## Types Use the `type` prop to set the type of input field to be displayed. Types include: `'text'`, `'email'`, `'tel'` and `'password'`. The default value is `'text'`. ### Text ```jsx live () => { const form = useFormV2({ defaultValues: { text: 'Type Text', }, }); return ( <V2FormProvider state={form}> <V2TextInput label="Type Text" type="text" model="text" /> </V2FormProvider> ); }; ``` ### Password ```jsx live () => { const form = useFormV2({ defaultValues: { password: 'SuperSecretPassword', }, }); return ( <V2FormProvider state={form}> <V2TextInput label="Type Text" type="password" model="password" autoComplete="new-password" isClearable /> </V2FormProvider> ); }; ``` #### Multi-step password validation Use the `requirementConfig` prop to display password requirements. The `requirementConfig` prop is an object that takes in two props, `title` and `items`. - `title` : The title for the password requirements. - `items` : An array of objects that define the password requirements. Each object in the array has three properties: `variant`, `test`, and `text`. - `variant` : This property can be `'success'`, `'default'`, or `'error'` . It is used to determine the style of the requirement message. - `text` : This property is the actual text of the requirement message. - `test` : This property requires a function that will be used to evaluate the password input. The function should return a boolean value, with `true` indicating that the password meets the requirement, and `false` indicating that it does not. Here's an example of how to use the `requirementConfig` prop: ```jsx const requirementConfig = { title: 'Password must have at least:', items: [ { test: (pwd) => /[A-Z]/.test(pwd), text: '1 capital letter', variant: 'default', }, { test: (pwd) => /[a-z]/.test(pwd), text: '1 lower case letter', variant: 'default', }, { test: (pwd) => /[0-9]/.test(pwd), text: '1 number', variant: 'default', }, { test: (pwd) => /[!@#$%^&()_+\-=\[\]{};':"\\|,.<>\/?]+/.test(pwd), text: '1 special character', variant: 'default', }, { test: (pwd) => pwd && pwd.length >= 8, text: '8 characters', variant: 'default', } ], } /> ``` To import the types for the `requirementConfig` prop, use can use the following: ```jsx import { RequirementConfigType, RequirementItemType, } from '@uhg-abyss/web/ui/TextInput'; ``` Note: Teams will need to handle all validation logic for determining password requirements. Refer to our [Validation](#validation) section for implementation examples. ```jsx live () => { const form = useFormV2(); const { formState: { isSubmitSuccessful }, } = form; const onSubmit = (data) => { console.log(data); }; const watchedPassword = form.watch('password'); const [requirementItems, setRequirementItems] = useState([ { test: (pwd) => /[A-Z]/.test(pwd), text: '1 capital letter', variant: 'default', }, { test: (pwd) => /[a-z]/.test(pwd), text: '1 lower case letter', variant: 'default', }, { test: (pwd) => /[0-9]/.test(pwd), text: '1 number', variant: 'default', }, { test: (pwd) => /[!@#$%^&()_+\-=\[\]{};':"\\|,.<>\/?]+/.test(pwd), text: '1 special character', variant: 'default', }, { test: (pwd) => pwd && pwd.length >= 8, text: '8 characters', variant: 'default', }, ]); useEffect(() => { if (typeof watchedPassword !== 'string') return; const updateConfig = requirementItems.map((config) => ({ ...config, variant: config.test(watchedPassword) ? 'success' : 'error', })); setRequirementItems(updateConfig); }, [watchedPassword]); const complexPasswordValidator = (value) => { const failingRequirement = requirementItems.find( ({ test }) => !test(value) ); return failingRequirement ? 'Does not meet all requirements' : true; }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2TextInput label="New password" model="password" type="password" isClearable isRequired successMessage="Password meets requirements!" validators={{ required: true, validate: complexPasswordValidator }} requirementConfig={{ title: 'Password must have at least:', items: requirementItems, }} /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ```jsx live () => { const isFirstMount = useRef(true); const [password, setPassword] = useState(''); const [error, setError] = useState(undefined); const [success, setSuccess] = useState(undefined); const [requirementItems, setRequirementItems] = useState([ { test: (pwd) => /[A-Z]/.test(pwd), text: '1 capital letter', variant: 'default', }, { test: (pwd) => /[a-z]/.test(pwd), text: '1 lower case letter', variant: 'default', }, { test: (pwd) => /[0-9]/.test(pwd), text: '1 number', variant: 'default', }, { test: (pwd) => /[!@#$%^&()_+\-=\[\]{};':"\\|,.<>\/?]+/.test(pwd), text: '1 special character', variant: 'default', }, { test: (pwd) => pwd && pwd.length >= 8, text: '8 characters', variant: 'default', }, ]); useEffect(() => { if (isFirstMount.current) { isFirstMount.current = false; return; } const updateConfig = requirementItems.map((config) => ({ ...config, variant: config.test(password) ? 'success' : 'error', })); setRequirementItems(updateConfig); }, [password]); const complexPasswordValidator = (value) => { const failingRequirement = requirementItems.find( ({ test }) => !test(value) ); return failingRequirement ? failingRequirement.text : true; }; const onSubmit = () => { const validationResult = complexPasswordValidator(password); if (validationResult === true) { setError(undefined); setSuccess('Password meets all requirements!'); console.log('Password is valid:', password); } else { setSuccess(undefined); setError(validationResult); console.error('Validation error:', validationResult); } }; const handlePasswordChange = (e) => { const newPassword = e.target.value; setPassword(newPassword); // If there is already an error or success message, validate the new password if (error !== undefined || success !== undefined) { const validationResult = complexPasswordValidator(newPassword); if (validationResult === true) { setError(undefined); setSuccess('Password meets all requirements!'); } else { setSuccess(undefined); setError(validationResult); } } }; return ( <form> <V2TextInput label="useState Example" type="password" value={password} errorMessage={error} successMessage={success} isClearable isRequired onChange={handlePasswordChange} onClear={() => { setPassword(''); setError(undefined); setSuccess(undefined); }} requirementConfig={{ title: 'Password must have at least:', items: requirementItems, }} /> <V2Button onClick={onSubmit} css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </form> ); }; ``` ## Masks Use the `mask` prop to set the masking variation of the input field. Default masks available: `'phone'`, `'date'`, `'zip'`, `'numeric'`, and `'ssn'`. While the use of a `placeholder` is generally not recommended, masking is one instance it can be used. See <ExitLink href="https://www.nngroup.com/articles/form-design-placeholders/">here</ExitLink> for more information. Further configuration can be set by usage of the `maskConfig` prop, which utilizes the <ExitLink href="https://s-yadav.github.io/react-number-format/docs/intro">react-number-format</ExitLink> library to take in an object of additional props. When `mask:"numeric"`, the `maskConfig` prop accepts <ExitLink href="https://s-yadav.github.io/react-number-format/docs/numeric_format">`NumericFormatProps`</ExitLink>. For all other mask types, `maskConfig` will accept <ExitLink href="https://s-yadav.github.io/react-number-format/docs/pattern_format">`PatternFormatProps`</ExitLink>. ```js // Numeric mask example { mask: 'numeric', maskConfig: NumericFormatProps = { thousandSeparator: ',', allowLeadingZeros: true, } } // Pattern mask example { mask: 'time', maskConfig: PatternFormatProps{ format: '##:##:##', } } ``` Please visit the <ExitLink href="https://s-yadav.github.io/react-number-format/docs/pattern_format">Pattern Format</ExitLink> and <ExitLink href="https://s-yadav.github.io/react-number-format/docs/numeric_format">Numeric Format</ExitLink> for detailed documentation on all available configuration settings. ### Phone ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2({ defaultValues: { phone: '5555551234', }, }); const [value, setValue] = useState('5555551234'); return ( <FormSpacing> <V2FormProvider state={form}> <V2TextInput label="Phone Mask (useForm)" mask="phone" placeholder="(_) _-__" model="phone" autoComplete="tel-local" /> </V2FormProvider> <V2TextInput label="Phone Mask (useState)" mask="phone" placeholder="(_) _-" value={value} onChange={(e) => setValue(e.target.value)} autoComplete="tel-local" /> </FormSpacing> ); }; ``` ### Date ```jsx live () => { const form = useFormV2({ defaultValues: { date: '01/01/2001', }, }); return ( <V2FormProvider state={form}> <V2TextInput label="Date Mask" mask="date" model="date" placeholder="mm/dd/yyyy" subText="Date Field Format: mm/dd/yyyy" /> </V2FormProvider> ); }; ``` ### Zip ```jsx live () => { const form = useFormV2({ defaultValues: { zip: '12345', }, }); return ( <V2FormProvider state={form}> <V2TextInput label="Zip Mask" mask="zip" model="zip" placeholder="_" autoComplete="postal-code" /> </V2FormProvider> ); }; ``` ### Social Security Number ```jsx live () => { const form = useFormV2({ defaultValues: { ssn: '111223333', }, }); return ( <V2FormProvider state={form}> <V2TextInput label="SSN Mask" mask="ssn" model="ssn" placeholder="_--__" /> </V2FormProvider> ); }; ``` ### Numeric ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2({ defaultValues: { numericConfig: '1123123.12', }, }); return ( <V2FormProvider state={form}> <FormSpacing> <V2TextInput label="Numeric Mask" mask="numeric" model="numeric" /> <V2TextInput label="Numeric Mask w/ Config" mask="numeric" model="numericConfig" maskConfig={{ thousandSeparator: ',', decimalScale: 2, }} /> </FormSpacing> </V2FormProvider> ); }; ``` ### Currency ```jsx live () => { const form = useFormV2({ defaultValues: { currency: '1123123.12', }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2TextInput label="Currency" mask="numeric" model="currency" returnUnmaskedValue maskConfig={{ thousandSeparator: ',', fixedDecimalScale: true, decimalScale: 2, prefix: '$', }} /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ### Return unmasked value Use the `returnUnmaskedValue` prop to return an unmasked value. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const Text = styled('p', { static: { marginBottom: '0', color: '$web.semantic.color.text.content.secondary', }, dynamic: () => { const typography = useToken('typography')( '$web.semantic.typography.p.md-reg' ); return { typography, }; }, }); const form = useFormV2({ defaultValues: { phone1: '1112223333', phone2: '(555) 444-3333', }, }); return ( <V2FormProvider state={form}> <FormSpacing> <V2TextInput label="Phone Mask" mask="phone" model="phone1" autoComplete="tel-local" returnUnmaskedValue /> <Text>Unmasked Value: {form.getValues('phone1')}</Text> <V2TextInput label="Phone Mask" mask="phone" model="phone2" autoComplete="tel-local" returnUnmaskedValue={false} /> <Text>Masked Value: {form.getValues('phone2')}</Text> </FormSpacing> </V2FormProvider> ); }; ``` ### Empty mask character Use the `emptyMaskChar` prop to replace the empty mask placeholder. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2({ defaultValues: { phone: '555', ssn: '555', }, }); return ( <V2FormProvider state={form}> <FormSpacing> <V2TextInput label="^ Mask" mask="phone" model="phone" autoComplete="tel-local" emptyMaskChar="^" /> <V2TextInput label=" Mask" mask="ssn" model="ssn" emptyMaskChar="" /> </FormSpacing> </V2FormProvider> ); }; ``` ### Custom mask patterns Pass in a custom pattern into the `mask` prop to create unique masks. The hash string, `#`, allows number inputs in place of the hash. Note: Providing a custom `mask` will use `PatternFormatProps` for the `maskConfig` prop. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2({ defaultValues: { customCC: '1234567891234567', customPhone: '1234567890', customCurrency: '50.25', }, }); return ( <V2FormProvider state={form}> <FormSpacing> <V2TextInput label="Custom Mask Credit Card" mask="#### #### #### ####" model="customCC" autoComplete="cc-number" /> <V2TextInput label="Custom Mask Phone" mask="+1 (###) ###-####" model="customPhone" autoComplete="tel-local" /> <V2TextInput label="Custom Currency Mask" model="customCurrency" mask="numeric" maskConfig={{ prefix: '$', decimalScale: 2, isAllowed: ({ floatValue }) => { const value = floatValue || 0; return value <= 99.99; }, }} /> </FormSpacing> </V2FormProvider> ); }; ``` ### Custom time mask ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'row', gap: '$web.semantic.spacing.scale.sm', alignItems: 'flex-end', }), [] ); const timeValueOnLoad = '23:11:50'; const convertToTwelveHourTime = (value) => { const [hours, minutes, seconds] = value.split(':'); const newHours = hours > 12 ? hours - 12 : hours; const newTime = `${newHours}${minutes}${seconds}`; return newTime; }; const getAmPmValue = (value) => { const time = value.split(':'); const hours = parseInt(time[0]); return hours >= 12 ? 'PM' : 'AM'; }; const form = useFormV2({ defaultValues: { customTime: convertToTwelveHourTime(timeValueOnLoad), customTimeAmPm: getAmPmValue(timeValueOnLoad), }, }); const amPmValue = form.watch('customTimeAmPm'); const convertToTwentyFourTime = (value) => { if (value.length !== 6) { return value; } const hours = value.substring(0, 2); const minutes = value.substring(2, 4); const seconds = value.substring(4, 6); const newHours = parseInt(hours) + (amPmValue === 'PM' ? 12 : 0); const newTime = `${newHours}:${minutes}:${seconds}`; return newTime; }; const onSubmit = (data) => { console.log('form data', data); const formData = Object.keys(data).reduce((acc, key) => { if (key === 'customTime') { acc[key] = convertToTwentyFourTime(data[key]); } else if (key === 'customTimeAmPm') { return acc; } else { acc[key] = data[key]; } return acc; }, {}); console.log('24 hour converted data', formData); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <FormSpacing> <V2TextInput label="Custom Time w/Seconds Mask" mask={`##:##:## ${amPmValue}`} model="customTime" returnUnmaskedValue /> <ToggleTabs label="AM/PM Selector" model="customTimeAmPm" hideLabel> <ToggleTabs.Tab label="AM" value="AM" /> <ToggleTabs.Tab label="PM" value="PM" /> </ToggleTabs> </FormSpacing> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2TextInput" propTypeName="TextInputProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2ClassesTable title="V2TextInput" classes={[TextInputClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> A combobox is a widget made up of the combination of two distinct elements: 1) a single-line textbox, and 2) an associated pop-up element for helping users set the value of the textbox. The popup may be a listbox, grid, tree, or dialog. Many implementations also include a third optional element -- a graphical button adjacent to the textbox, indicating the availability of the popup. Activating the button displays the popup if suggestions are available. Adheres to the <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/combobox/">Combo box WAI-ARIA design pattern</ExitLink>. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); return ( <V2FormProvider state={form}> <FormSpacing> <V2TextInput label="First Name" model="custom-required" validators={{ required: 'Enter your given name' }} /> <V2TextInput label="Last name" model="required" subText="Spaces allowed" validators={{ required: 'Enter your family name' }} /> <V2TextInput label="Email address" model="pattern" autoComplete="email" subText="Example: myName@gmail.com" validators={{ required: 'You email is required to receive offers', pattern: { value: /^(([^<>()[\]\\.,;:\s@\"]+(\.[^<>()[\]\\.,;:\s@\"]+))|(\".+\"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/, message: 'Enter a valid email address', }, }} /> </FormSpacing> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` <h3>Multi-Step Messaging</h3> ```jsx live () => { const form = useFormV2(); const { formState: { isSubmitSuccessful }, } = form; const onSubmit = (data) => { console.log(data); }; const watchedPassword = form.watch('password'); const [requirementItems, setRequirementItems] = useState([ { test: (pwd) => /[A-Z]/.test(pwd), text: '1 capital letter', variant: 'default', }, { test: (pwd) => /[a-z]/.test(pwd), text: '1 lower case letter', variant: 'default', }, { test: (pwd) => /[0-9]/.test(pwd), text: '1 number', variant: 'default', }, { test: (pwd) => /[!@#$%^&()_+\-=\[\]{};':"\\|,.<>\/?]+/.test(pwd), text: '1 special character', variant: 'default', }, { test: (pwd) => pwd && pwd.length >= 8, text: '8 characters', variant: 'default', }, ]); useEffect(() => { if (typeof watchedPassword !== 'string') return; const updateConfig = requirementItems.map((config) => ({ ...config, variant: config.test(watchedPassword) ? 'success' : 'error', })); setRequirementItems(updateConfig); }, [watchedPassword]); const complexPasswordValidator = (value) => { const failingRequirement = requirementItems.find( ({ test }) => !test(value) ); return failingRequirement ? 'Does not meet all requirements' : true; }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2TextInput label="New password" model="password" type="password" isClearable isRequired successMessage="Password meets requirements!" validators={{ required: true, validate: complexPasswordValidator }} requirementConfig={{ title: 'Password must have at least:', items: requirementItems, }} /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ```jsx render <Docs.AccessibilityTable title="Textbox" rows={[ { name: 'Down Arrow', description: 'If the listbox is displayed: Moves focus to the second suggested value. Note that the first value is automatically selected. If the listbox is not displayed: opens the listbox and moves focus to the first value.', }, { name: 'Up Arrow', description: 'If the listbox is displayed, moves focus to the last suggested value. If the listbox is not displayed, opens the listbox and moves focus to the last value.', }, { name: 'Alt + Down Arrow', description: 'Opens the listbox without moving focus or changing selection.', }, { name: 'Enter', description: 'If the listbox is displayed and the first option is automatically selected: Sets the textbox value to the content of the selected option. Closes the listbox.', }, { name: 'Esc', description: 'Clears the textbox. If the listbox is displayed, closes it.', }, { name: 'Supported Keystrokes', description: 'Supported keystrokes use character matching functionality to display matched values in the Listbox.', }, ]} /> ``` ```jsx render <Docs.AccessibilityTable title="Listbox" rows={[ { name: 'Enter', description: 'Sets the textbox value to the content of the focused option in the listbox. Closes the listbox. Sets focus on the textbox.', }, { name: 'Esc', description: 'Closes the listbox. Sets focus on the textbox. Clears the textbox.', }, { name: 'Down Arrow', description: 'Moves focus to the next option. If focus is on the last option, moves focus to the first option.', }, { name: 'Up Arrow', description: 'Moves focus to the previous option. If focus is on the first option, moves focus to the last option.', }, { name: 'Right Arrow', description: 'Moves focus to the textbox and moves the editing cursor one character to the right.', }, { name: 'Left Arrow', description: 'Moves focus to the textbox and moves the editing cursor one character to the left.', }, { name: 'Home', description: 'Moves focus to the textbox and places the editing cursor at the beginning of the field.', }, { name: 'End', description: 'Moves focus to the textbox and places the editing cursor at the end of the field.', }, ]} /> ``` </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={TextInput} keys={['inputV2']} /> ``` ```jsx render <Docs.ComponentTokensTable of={'Add Ons'} keys={['inputAddOnsV2']} /> ``` ```jsx render <Docs.ComponentTokensTable of={'Header'} keys={['inputHeaderV2']} /> ``` ```jsx render <Docs.ComponentTokensTable of={'Validation'} keys={['inputValidationV2']} /> ``` ```jsx render <Docs.ComponentTokensTable of={'Pass Requirement'} keys={['inputPassRequirementV2']} /> ``` </Tab> --- id: text-input category: Forms title: TextInput description: Allows users to enter text into a UI. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=641-11876 subDirectory: TextInput/v1 --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="TextInput"></Docs.V2MigrationBanner> ``` ```jsx import { TextInput } from '@uhg-abyss/web/ui/TextInput'; ``` ```jsx sandbox { component: 'TextInput', inputs: [ { prop: 'errorMessage', type: 'string', }, { prop: 'placeholder', type: 'string', }, { prop: 'subText', type: 'string', }, { prop: 'width', type: 'string', }, { prop: 'mask', type: 'select', isClearable: true, options: [ { label: 'Phone', value: 'phone' }, { label: 'SSN', value: 'ssn' }, { label: 'Date', value: 'date' }, { label: 'Zipcode', value: 'zip' }, { label: 'Numeric', value: 'numeric' }, ] }, { prop: 'type', type: 'select', isClearable: true, options: [ { label: 'Text', value: 'text' }, { label: 'Password', value: 'password' }, { label: 'Search', value: 'search' }, ] }, { prop: 'hideLabel', type: 'boolean', }, { prop: 'isClearable', type: 'boolean', }, { prop: 'isDisabled', type: 'boolean', }, { prop: 'highlighted', type: 'boolean', defaultValue: false, }, ] } () => { const [value, setValue] = useState('State Default Value'); return ( <TextInput label="TextInput Sandbox" value={value} onChange={(e) => setValue(e.target.value)} onClear={() => setValue('')} /> ); }; ``` ## useForm (recommended) Using the `useForm` hook for handling TextInput lets the DOM handle form data. ```jsx live () => { const form = useForm({ defaultValues: { textForm: 'init', }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <TextInput label="TextInput Form" placeholder="Form" model="textForm" isClearable validators={{ required: true }} /> <Button type="submit" style={{ marginTop: 15 }}> Submit </Button> </FormProvider> ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [value, setValue] = useState(''); const onSubmit = () => { console.log('value', value); }; return ( <React.Fragment> <TextInput label="TextInput useState" placeholder="State" value={value} isClearable onChange={(e) => setValue(e.target.value)} onClear={() => setValue('')} /> <Button onClick={onSubmit} style={{ marginTop: 15 }}> Submit </Button> </React.Fragment> ); }; ``` ## Placeholder Use the `placeholder` prop to give users a short description in the input field before they enter a value. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <TextInput label="Placeholder" placeholder="Placeholder" model="placeholder" /> </FormProvider> ); }; ``` ## Add elements inside input Use the `inputLeftElement` and `inputRightElement` props to add elements to the inside of the text input field. The recommended usage is for inserting icons. These are considered decorative and do not need to be exposed to screen readers. That said, please note that icons should _not_ provide any information that is not also conveyed in a screen-readable way. For example, an (!) icon to indicate errors needs to be accompanied by `aria-invalid`. If icons are used to convey additional information, use the `inputLeftElementDescription` and `inputRightElementDescription` props to provide a description for screen readers. The maximum width for the `inputRightElement` is `35px`. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <TextInput label="Add Elements" placeholder="Placeholder Text" model="addElement" isClearable inputLeftElement={ <IconSymbol icon="phone" size="18px" color="$gray6" /> } inputRightElement={<IconSymbol icon="check" size="20px" />} inputLeftElementDescription="Phone Icon" inputRightElementDescription="Checkmark Icon" /> </FormProvider> ); }; ``` ## Add-ons Use the `leftAddOn` and `rightAddOn` props to add add-ons to the outside of the text input field. The recommended usage is for inserting supplemental text. It is recommended to use the `leftAddOnDescription` and `rightAddOnDescription` props to communicate the purpose of the add-ons to screen reader users. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <TextInput label="Left Add-Ons" placeholder="Placeholder Text" model="leftAddOn" isClearable leftAddOn="http://" leftAddOnDescription="URL Prefix" /> <TextInput label="Right Add-Ons" placeholder="Placeholder Text" model="rightAddOn" isClearable leftAddOn="http://" rightAddOn=".com" leftAddOnDescription="URL Prefix" rightAddOnDescription="URL Suffix" /> </FormProvider> ); }; ``` ## Sub text Use the `subText` prop to display helpful text below the input field. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <TextInput label="Sub Text" model="subText" subText="Custom Sub Text" /> </FormProvider> ); }; ``` ## Error message Use the `errorMessage` prop to display a custom error message below the input field. Note: The errorMessage prop does not work with useForm and is only applicable within our form input components when useState is being utilized. See the [useForm Docs](/web/hooks/use-form#set-error) for example use cases with useForm. ```jsx live () => { const [value, setValue] = useState('init'); const form = useForm(); return ( <FormProvider state={form}> <TextInput label="Input With Error" errorMessage="Error Message" value={value} isClearable onChange={(e) => setValue(e.target.value)} onClear={() => setValue('')} /> <TextInput label="Input Add-Ons With Error" errorMessage="Error Message" value={value} isClearable onChange={(e) => setValue(e.target.value)} onClear={() => setValue('')} leftAddOn="http://" rightAddOn=".com" leftAddOnDescription="URL Prefix" rightAddOnDescription="URL Suffix" /> </FormProvider> ); }; ``` ## Descriptors display Use the `descriptorsDisplay` prop to set the orientation of the error message and subtext descriptor content. Available variants include 'column' and 'row'. The default is set to 'row'. Use the [FormProvider](/web/ui/form-provider#descriptors-display) and `descriptorsDisplay` to set the descriptors orientation across an entire form. ```jsx live () => { const [value, setValue] = useState(''); return ( <TextInput onChange={(e) => setValue(e.target.value)} value={value} label="Descriptors Display" subText="Subtext Message" errorMessage="Error Message" descriptorsDisplay="column" /> ); }; ``` ## Label Use the `label` prop to display a label above the input. To hide the input label, set `hideLabel` to `true`. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <TextInput label="Custom Label" placeholder="Custom Label" model="custom-label" /> <TextInput label="Hidden Label" placeholder="Hidden Label" model="custom-hidden-label" hideLabel /> </FormProvider> ); }; ``` ## Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip) or a [Popover](/web/ui/popover). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <TextInput label="Default Helper" helper="This is a tooltip" model="helper-tooltip" /> <TextInput label="Custom Helper" helper={ <Popover title="Custom Helper" content="This is a popover with a custom icon" > <IconSymbol icon="help" variant="outlined" color="$success1" size="$sm" /> </Popover> } model="helper-custom" validators={{ required: true }} /> </FormProvider> ); }; ``` ## Clearable Set the `isClearable` prop to `true` to display a clear button in the input field. Use the `onClear` prop to handle the clear action. ```jsx live () => { const form = useForm({ defaultValues: { clearable: 'Clearable', }, }); return ( <FormProvider state={form}> <TextInput label="Clearable" model="clearable" isClearable={true} /> </FormProvider> ); }; ``` ## Disabled Set the `isDisabled` prop to `true` to disable the input field, so users cannot enter a value. ```jsx live () => { const form = useForm({ defaultValues: { disabled: 'Disabled', }, }); return ( <FormProvider state={form}> <TextInput isDisabled={true} label="Disabled" model="disabled" /> <TextInput isDisabled={true} label="Add-Ons with Disabled" model="disabled" leftAddOn="http://" rightAddOn=".com" leftAddOnDescription="URL Prefix" rightAddOnDescription="URL Suffix" /> </FormProvider> ); }; ``` ## Max length Use the `maxLength` prop to limit the number of characters allowed in the input field. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <TextInput label="Max Length" maxLength={4} model="maxLength" placeholder="Type to see character limit" /> </FormProvider> ); }; ``` ## Formatter Use the `formatter` prop to format values on change for text inputs. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <TextInput label="Replace special characters with empty string" model="replaceSpecialCharacters" placeholder="Replace special characters with empty string" formatter={(value) => { return value.replace(/[&\/\\#,+()$~%.'":?<>{}]/g, ''); }} /> <TextInput label="Uppercase Characters" model="uppercase" placeholder="Uppercase Characters" formatter={(value) => { return value.toUpperCase(); }} /> </FormProvider> ); }; ``` ## Auto complete Use the `autoComplete` prop whenever you are collecting information about the user. Head to <ExitLink href="https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete">Mozilla</ExitLink> to find all of the autocomplete options. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <TextInput label="Auto Complete" placeholder="Phone" mask="phone" model="autocomplete" autoComplete="tel-local" /> </FormProvider> ); }; ``` ## Highlighted Use the `highlighted` prop to enable the background color for the input. You can use `FormProvider` and `highlighted` to enable the color to appear if validation is required. ```jsx live () => { const [value, setValue] = useState(''); return ( <TextInput label="TextInput useState" placeholder="State" value={value} isClearable highlighted onChange={(e) => setValue(e.target.value)} onClear={() => setValue('')} /> ); }; ``` ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit} highlighted> <TextInput label="TextInput Form" placeholder="Form" model="textForm" isClearable validators={{ required: true }} /> <Button type="submit" style={{ marginTop: 15 }}> Submit </Button> </FormProvider> ); }; ``` ## Masks Use the `mask` prop to set the masking variation of the input field. Included masks: `'phone'`, `'date'`, `'zip'`, `'dollar'`, `'numeric'`, and `'ssn'`. Further configuration can be set by usage of the `maskConfig` prop, which utilizes the react-number-format library to take in an object of additional props. For example: ```js maskConfig: { thousandSeperator: ',', allowLeadingZeros: true, } ``` Please visit the <ExitLink href="https://github.com/s-yadav/react-number-format/blob/master/documentation/v4.md">react-number-format docs</ExitLink> for detailed documentation on all available configuration settings. ### Phone ```jsx live () => { const form = useForm({ defaultValues: { phone: '5555551234', }, }); const [value, setValue] = useState('5555551234'); return ( <React.Fragment> <FormProvider state={form}> <TextInput label="Phone Mask" placeholder="(_) _-__" mask="phone" model="phone" autoComplete="tel-local" /> </FormProvider> <TextInput label="Phone Mask" placeholder="(_) _-" mask="phone" value={value} onChange={(e) => setValue(e.target.value)} autoComplete="tel-local" /> </React.Fragment> ); }; ``` ### Date ```jsx live () => { const form = useForm({ defaultValues: { date: '01/01/2001', }, }); return ( <FormProvider state={form}> <TextInput label="Date Mask" mask="date" model="date" subText="Date Field Format: mm/dd/yyyy" placeholder="mm/dd/yyyy" /> </FormProvider> ); }; ``` ### Zip ```jsx live () => { const form = useForm({ defaultValues: { zip: '12345', }, }); return ( <FormProvider state={form}> <TextInput label="Zip Mask" mask="zip" model="zip" autoComplete="postal-code" placeholder="_" /> </FormProvider> ); }; ``` ### Social Security Number ```jsx live () => { const form = useForm({ defaultValues: { ssn: '111223333', }, }); return ( <FormProvider state={form}> <TextInput label="SSN Mask" mask="ssn" model="ssn" placeholder="_--__" /> </FormProvider> ); }; ``` ### Numeric ```jsx live () => { const form = useForm({ defaultValues: { numericConfig: '1123123.12', }, }); return ( <FormProvider state={form}> <TextInput label="Numeric Mask" mask="numeric" model="numeric" /> <TextInput label="Numeric Mask w/ Config" mask="numeric" model="numericConfig" maskConfig={{ thousandSeparator: ',', decimalScale: 2, }} /> </FormProvider> ); }; ``` ### Currency ```jsx live () => { const form = useForm({ defaultValues: { currency: '1123123.12', }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <TextInput label="Currency" mask="numeric" model="currency" returnUnmaskedValue maskConfig={{ thousandSeparator: ',', fixedDecimalScale: true, decimalScale: 2, prefix: '$', }} /> <Button type="submit" style={{ marginTop: 15 }}> Submit </Button> </FormProvider> ); }; ``` ### Return unmasked value Use the `returnUnmaskedValue` prop to return an unmasked value. ```jsx live () => { const form = useForm({ defaultValues: { phone1: '1112223333', phone2: '(555) 444-3333', }, }); return ( <FormProvider state={form}> <TextInput label="Phone Mask" mask="phone" model="phone1" autoComplete="tel-local" returnUnmaskedValue /> <p>Unmasked Value: {form.getValues('phone1')}</p> <TextInput label="Phone Mask" mask="phone" model="phone2" autoComplete="tel-local" returnUnmaskedValue={false} /> <p>Masked Value: {form.getValues('phone2')}</p> </FormProvider> ); }; ``` ### Empty mask character Use the `emptyMaskChar` prop to replace the empty mask placeholder. ```jsx live () => { const form = useForm({ defaultValues: { phone: '555', ssn: '555', }, }); return ( <FormProvider state={form}> <TextInput label="^ Mask" mask="phone" model="phone" autoComplete="tel-local" emptyMaskChar="^" /> <TextInput label="* Mask" mask="ssn" model="ssn" emptyMaskChar="" /> </FormProvider> ); }; ``` ### Custom mask patterns Pass in a custom pattern into the `mask` prop to create unique masks. The hash string, `#`, allows number inputs inplace of the hash. ```jsx live () => { const form = useForm({ defaultValues: { customCC: '1234567891234567', customPhone: '1234567890', customCurrency: '50.25', }, }); return ( <FormProvider state={form}> <TextInput label="Custom Mask Credit Card" mask="#### #### #### ####" model="customCC" autoComplete="cc-number" /> <TextInput label="Custom Mask Phone" mask="+1 (###) ###-####" model="customPhone" autoComplete="tel-local" /> <TextInput label="Custom Currency Mask" model="customCurrency" mask="numeric" maskConfig={{ prefix: '$', decimalScale: 2, isAllowed: ({ floatValue }) => { const value = floatValue || 0; return value <= 99.99; }, }} /> </FormProvider> ); }; ``` ### Custom time mask ```jsx live () => { const timeValueOnLoad = '23:11:50'; const convertToTwelveHourTime = (value) => { const [hours, minutes, seconds] = value.split(':'); const newHours = hours > 12 ? hours - 12 : hours; const newTime = `${newHours}${minutes}${seconds}`; return newTime; }; const getAmPmValue = (value) => { const time = value.split(':'); const hours = parseInt(time[0]); return hours >= 12 ? 'PM' : 'AM'; }; const form = useForm({ defaultValues: { customTime: convertToTwelveHourTime(timeValueOnLoad), customTimeAmPm: getAmPmValue(timeValueOnLoad), }, }); const amPmValue = form.watch('customTimeAmPm'); const convertToTwentyFourTime = (value) => { if (value.length !== 6) { return value; } const hours = value.substring(0, 2); const minutes = value.substring(2, 4); const seconds = value.substring(4, 6); const newHours = parseInt(hours) + (amPmValue === 'PM' ? 12 : 0); const newTime = `${newHours}:${minutes}:${seconds}`; return newTime; }; const onSubmit = (data) => { console.log('form data', data); const formData = Object.keys(data).reduce((acc, key) => { if (key === 'customTime') { acc[key] = convertToTwentyFourTime(data[key]); } else if (key === 'customTimeAmPm') { return acc; } else { acc[key] = data[key]; } return acc; }, {}); console.log('24 hour converted data', formData); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <Layout.Group> <TextInput label="Custom Time w/Seconds Mask" mask={`##:##:## ${amPmValue}`} model="customTime" returnUnmaskedValue /> <ToggleTabs label="AM/PM Selector" model="customTimeAmPm" css={{ 'abyss-toggle-tabs-label': { visibility: 'hidden' } }} > <ToggleTabs.Tab label="AM" value="AM" /> <ToggleTabs.Tab label="PM" value="PM" /> </ToggleTabs> </Layout.Group> <Button type="submit">Submit</Button> </FormProvider> ); }; ``` ## Types Use the `type` prop to set the type of input field to be displayed. Types include: `'text'`, `'email'`, `'tel'`, `'password'`, and `'search'`. ### Text ```jsx live () => { const form = useForm({ defaultValues: { text: 'Type Text', }, }); return ( <FormProvider state={form}> <TextInput label="Type Text" type="text" model="text" /> </FormProvider> ); }; ``` ### Password ```jsx live () => { const form = useForm({ defaultValues: { password: 'SuperSecretPassword', }, }); return ( <FormProvider state={form}> <TextInput label="Type Text" type="password" model="password" autoComplete="new-password" isClearable /> </FormProvider> ); }; ``` ### Search Use the `onClickSearch` prop to set the callback for the search button. ```jsx live () => { const [value, setValue] = React.useState('Text'); const handleSearch = () => { console.log('value: ', value); }; return ( <TextInput type="search" label="Search" value={value} onChange={(e) => setValue(e.target.value)} onClear={() => setValue('')} onClickSearch={handleSearch} isClearable leftAddOn="http://" rightAddOn=".com" leftAddOnDescription="URL Prefix" rightAddOnDescription="URL Suffix" inputRightElement={<IconSymbol icon="phone" size="18px" color="$gray6" />} inputRightElementDescription="Phone Icon" /> ); }; ``` ## Validation Use the `validators` prop to set rules for the field to be valid. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <TextInput label="Required Default Message" model="required" validators={{ required: true }} /> <TextInput label="Required Custom Message" model="custom-required" validators={{ required: 'Custom Error Message' }} /> <TextInput label="Min Length" model="minLength" validators={{ required: true, minLength: { value: 4, message: 'Min Length 4', }, }} /> <TextInput label="Max Length" model="maxLength" validators={{ required: true, maxLength: { value: 4, message: 'Max Length 4', }, }} /> <TextInput label="Custom Pattern (Email)" model="pattern" autoComplete="email" validators={{ required: true, pattern: { value: /^(([^<>()[\]\\.,;:\s@\"]+(\.[^<>()[\]\\.,;:\s@\"]+))|(\".+\"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/, message: 'Invalid Email', }, }} /> <TextInput label="Custom Validators" model="validate" validators={{ validate: { positive: (v) => parseInt(v) > 0 || 'should be greater than 0', lessThanTen: (v) => parseInt(v) < 10 || 'should be lower than 10', // you can do asynchronous validation as well //checkUrl: async () => await fetch() || 'error message', messages: (v) => !v && ['otherInput1', 'otherInput2'], }, }} /> <Button type="submit" style={{ marginTop: 15 }}> Submit </Button> </FormProvider> ); }; ``` ## Width Use the `width` prop to set the width of the input field. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <TextInput label="Width Default" model="width1" placeholder="Default Width" isClearable /> <TextInput width="75%" label="Width 75%" model="width2" placeholder="Width Set To 75%" isClearable /> <TextInput width="335px" model="width3" label="Width 335px" placeholder="Width Set To 335px" isClearable /> </FormProvider> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={TextInput} rows={[ { name: 'label', type: 'string', description: 'Label for input field', }, { name: 'helper', type: 'node | string', description: 'Helper element next to label', }, { name: 'placeholder', type: 'string', description: 'Short description displayed in the input before the user enters a value', }, { name: 'isDisabled', type: 'boolean', description: 'Flag to enable/disable the input. If true, the input will be disabled', }, { name: 'isClearable', type: 'boolean', description: 'Flag to display/hide a clear button. If true, a clear button will be visable to the user', }, { name: 'isRequired', type: 'boolean', description: 'Flag to require text', }, { name: 'returnUnmaskedValue', type: 'boolean', description: 'Flag to return masked or unmasked value. If true, the value will be unmasked', }, { name: 'returnMaskAsNumber', type: 'boolean', description: 'Flag to return value as masked number', }, { name: 'value', type: 'number | string', description: 'Value of the text input', }, { name: 'validators', type: 'object', description: 'Set rules for the input field to be valid', }, { name: 'css', type: 'shape', description: 'Stitches styling', }, { name: 'onChange', type: 'function', description: 'Callback fired every time the value changes', }, { name: 'onClear', type: 'function', description: 'Callback fired when user clicks the clear button. The isClearable property must be set to true', }, { name: 'onClickSearch', type: 'function', description: 'Callback fired when user clicks the search button.', }, { name: 'onFocus', type: 'function', description: 'Callback fired every time the component is focused', }, { name: 'onBlur', type: 'function', description: 'Callback fired every time the component is unfocused', }, { name: 'onKeyDown', type: 'function', description: 'Callback fired every time a key is pressed while focused in the component', }, { name: 'onPaste', type: 'function', description: 'Callback fired every time something is pasted into the component', }, { name: 'model', type: 'string', description: 'Unique identifier used for FormProvider', }, { name: 'mask', type: "'phone' | 'zip' | 'date' | 'ssn' | 'numeric'", description: 'Format of the input value', }, { name: 'maskConfig', type: 'shape', description: 'Set configs for mask utilized by the react-number-format library', }, { name: 'type', type: 'string', description: 'Set the type of input field', }, { name: 'width', type: 'string', description: 'Width of the input field', }, { name: 'errorMessage', type: 'string', description: 'Error message to be displayed below input field', }, { name: 'emptyMaskChar', type: 'string', description: 'Character placeholder for empty mask inputs', }, { name: 'autoComplete', type: 'string', description: 'The autocomplete status that is passed to the form element in the FormProvider', }, { name: 'subText', type: 'string', description: 'Set the text displayed below input field', }, { name: 'descriptorsDisplay', type: '"row" | "column"', description: 'Set the orientation of descriptor content located below input field', }, { name: 'hideLabel', type: 'boolean', description: 'Flag to show or hide label', }, { name: 'formatter', type: 'function', description: 'Function used to format value on change', }, { name: 'inputLeftElement', type: 'node', description: 'Add element to left of inside text input', }, { name: 'inputRightElement', type: 'node', description: 'Add element to right of inside text input', }, { name: 'inputLeftElementDescription', type: 'string', description: 'Screen reader description for the left input element', }, { name: 'inputRightElementDescription', type: 'string', description: 'Screen reader description for the right input element', }, { name: 'leftAddOn', type: 'node', description: 'Add Addon to left of outside text input', }, { name: 'rightAddOn', type: 'node', description: 'Add Addon to right of outside text input', }, { name: 'leftAddOnDescription', type: 'string', description: 'Screen reader description for the left add-on', }, { name: 'rightAddOnDescription', type: 'string', description: 'Screen reader description for the right add-on', }, { name: 'highlighted', type: 'boolean', description: 'Render input with highlighted background', }, { name: 'preserveWhitespace', type: 'boolean', description: 'Set to true to preserve leading and trailing whitespace', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={TextInput} rows={[ { name: 'text-input-root', description: 'TextInput root element', }, { name: 'text-input-label', description: 'FormInput label', }, { name: 'text-input-clear', description: 'FormInput clear', }, { name: 'text-input-descriptors', description: 'Descriptor for FormInput', }, { name: 'text-input-left-add-on', description: 'Content for Left AddOn', }, { name: 'text-input-right-add-on', description: 'Content for Right AddOn', }, { name: 'text-input-left-element', description: 'Content for Left Element', }, { name: 'text-input-left-element-wrapper', description: 'Wrapper for Left Element', }, { name: 'text-input-right-element', description: 'Content for Right Element', }, { name: 'text-input-right-element-wrapper', description: 'Wrapper for Right Element', }, { name: 'form-input-wrapper-container', description: 'Wrapper container for input elements', }, ]} /> ``` </Tab> <Tab label="Accessibility"> A combobox is a widget made up of the combination of two distinct elements: 1) a single-line textbox, and 2) an associated pop-up element for helping users set the value of the textbox. The popup may be a listbox, grid, tree, or dialog. Many implementations also include a third optional element -- a graphical button adjacent to the textbox, indicating the availability of the popup. Activating the button displays the popup if suggestions are available. Adheres to the <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/combobox/">Combo box WAI-ARIA design pattern</ExitLink>. ```jsx live () => { const [value, setValue] = useState(''); const onSubmit = () => { console.log('value', value); }; return ( <React.Fragment> <TextInput label="TextInput useState" placeholder="State" value={value} isClearable onChange={(e) => setValue(e.target.value)} onClear={() => setValue('')} /> <Button onClick={onSubmit} style={{ marginTop: 15 }}> Submit </Button> </React.Fragment> ); }; ``` ```jsx render <Docs.AccessibilityTable title="Textbox" rows={[ { name: 'Down Arrow', description: 'If the listbox is displayed: Moves focus to the second suggested value. Note that the first value is automatically selected. If the listbox is not displayed: opens the listbox and moves focus to the first value.', }, { name: 'Up Arrow', description: 'If the listbox is displayed, moves focus to the last suggested value. If the listbox is not displayed, opens the listbox and moves focus to the last value.', }, { name: 'Alt + Down Arrow', description: 'Opens the listbox without moving focus or changing selection.', }, { name: 'Enter', description: 'If the listbox is displayed and the first option is automatically selected: Sets the textbox value to the content of the selected option. Closes the listbox.', }, { name: 'Esc', description: 'Clears the textbox. If the listbox is displayed, closes it.', }, { name: 'Supported Keystrokes', description: 'Supported keystrokes use character matching functionality to display matched values in the Listbox.', }, ]} /> ``` ```jsx render <Docs.AccessibilityTable title="Listbox" rows={[ { name: 'Enter', description: 'Sets the textbox value to the content of the focused option in the listbox. Closes the listbox. Sets focus on the textbox.', }, { name: 'Esc', description: 'Closes the listbox. Sets focus on the textbox. Clears the textbox.', }, { name: 'Down Arrow', description: 'Moves focus to the next option. If focus is on the last option, moves focus to the first option.', }, { name: 'Up Arrow', description: 'Moves focus to the previous option. If focus is on the first option, moves focus to the last option.', }, { name: 'Right Arrow', description: 'Moves focus to the textbox and moves the editing cursor one character to the right.', }, { name: 'Left Arrow', description: 'Moves focus to the textbox and moves the editing cursor one character to the left.', }, { name: 'Home', description: 'Moves focus to the textbox and places the editing cursor at the beginning of the field.', }, { name: 'End', description: 'Moves focus to the textbox and places the editing cursor at the end of the field.', }, ]} /> ``` </Tab> --- id: text-input-area-v2 category: Forms title: V2TextInputArea description: Allows users to enter multi-line text into a UI. design: https://www.figma.com/design/a8XbEI7AmNb94mOBgYUB7y/v1.73.0-Web-Abyss-Global%E2%80%A8Component-Library?node-id=11061-33&t=r7TVXkMFenyVaS1E-4&fuid=1279152000909006209 subDirectory: TextInputArea/v2 sourceIsTS: true --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="TextInputArea"></Docs.V2MigrationBanner> ``` ```jsx import { V2TextInputArea } from '@uhg-abyss/web/ui/TextInputArea'; ``` ```jsx sandbox { component: 'V2TextInputArea', inputs: [ { prop: 'subText', type: 'string', }, { prop: 'maxLength', type: 'number', }, { prop: 'hideLabel', type: 'boolean', }, { prop: 'isDisabled', type: 'boolean', }, { prop: 'isRequired', type: 'boolean', }, ], } () => { const [value, setValue] = useState('State Default Value'); return ( <V2TextInputArea label="V2TextInputArea Sandbox" value={value} onChange={(e) => setValue(e.target.value)} /> ); }; ``` ## useForm (recommended) Using the `useForm` hook for handling V2TextInputArea lets the DOM handle form data. ```jsx live () => { const form = useFormV2({ defaultValues: { textForm: 'Form Value', }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2TextInputArea label="V2TextInputArea useForm" model="textForm" validators={{ required: true }} /> <V2Button type="submit" style={{ marginTop: 15 }}> Submit </V2Button> </V2FormProvider> ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [value, setValue] = useState('State Default Value'); return ( <V2TextInputArea label="V2TextInputArea useState" value={value} onChange={(e) => setValue(e.target.value)} /> ); }; ``` ## Label Use the `label` prop to display a label above the input. To hide the input label set `hideLabel` to `true`. Use `isRequired` and `isOptional` for further customization. Note: If using `useForm`, do not use `isRequired`. The same functionality can be achieved with `required: true` in `validators`. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', flexGrow: 0, '.abyss-text-input-area': { height: '48px', }, }), [] ); const form = useFormV2(); return ( <V2FormProvider state={form}> <FormSpacing> <V2TextInputArea label="Custom Label" model="custom-label" /> <V2TextInputArea label="Hidden Label" model="custom-hidden-label" hideLabel /> <V2TextInputArea label="Required Label" model="custom-req-label" isRequired /> <V2TextInputArea label="Optional Label" model="custom-opt-label" isOptional /> </FormSpacing> </V2FormProvider> ); }; ``` ## Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip-v2) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip-v2) or a [Popover](/web/ui/popover-v2). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip-v2/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); return ( <V2FormProvider state={form}> <FormSpacing> <V2TextInputArea label="Default Helper" helper="This is a tooltip" model="helper-tooltip" /> <V2TextInputArea label="Custom Helper" helper={ <V2Popover title="Custom Helper" content="This is a popover" /> } model="helper-custom" /> </FormSpacing> </V2FormProvider> ); }; ``` ## Subtext Use the `subText` prop to display helpful information related to the input field. The prop accepts either a string or an object of the form: ```ts { text: string; position: 'above' | 'below'; } ``` The `position` property determines where the subtext will be displayed in relation to the input field. The default value is `'below'`. ```jsx live () => { const form = useFormV2(); return ( <V2FormProvider state={form}> <V2TextInputArea label="Sub Text" model="subText" subText={{ text: 'Custom Sub Text', position: 'above' }} /> </V2FormProvider> ); }; ``` ## Disabled Set the `isDisabled` prop to `true` to disable the input field so users cannot enter a value. ```jsx live () => { const form = useFormV2({ defaultValues: { disabled: 'Disabled', }, }); return ( <V2FormProvider state={form}> <V2TextInputArea isDisabled={true} label="Disabled" model="disabled" /> </V2FormProvider> ); }; ``` ## Validation ### Validators (useFormV2) ```jsx render <Docs.FormCompatibilityWidget useForm /> ``` Use the `validators` prop to set validation rules for the field when using `useFormV2`. See the examples below for implementation on various types of validation. Note: The default error message when `required` is `true` is minimally acceptable for accessibility. It is highly recommended to customize it to be more specific to the use of the field and form. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); return ( <V2FormProvider state={form}> <FormSpacing> <V2TextInputArea label="Required Default Message" model="required" validators={{ required: true }} /> <V2TextInputArea label="Required Custom Message" model="custom-required" validators={{ required: 'Custom Error Message' }} /> <V2TextInputArea label="Min Length" model="minLength" validators={{ required: true, minLength: { value: 4, message: 'Min Length 4', }, }} /> </FormSpacing> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ### Error message (useState) ```jsx render <Docs.FormCompatibilityWidget useState /> ``` Use the `errorMessage` prop to display a custom error message below the input field when using `useState`. ```jsx live () => { const [value, setValue] = useState('State Default Value'); return ( <V2TextInputArea label="Error Message" value={value} onChange={(e) => setValue(e.target.value)} errorMessage="Custom Error Message" /> ); }; ``` ### Success message ```jsx render <Docs.FormCompatibilityWidget useForm useState /> ``` Use the `successMessage` prop to display a custom success message below the input field. To provide a single success message across all form input components using `useFormV2`/`V2FormProvider`, you can provide `successMessage` to `V2FormProvider` as shown [here](/web/ui/form-provider-v2#successmessage). ```jsx live () => { const form = useFormV2(); const onSubmit = (data) => { // Do something on submit console.log(data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2TextInputArea data-testid="email" label="Success Message (useForm)" model="success" successMessage="Value submitted successfully" validators={{ required: 'Value is required', }} /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ```jsx live () => { const inputRef = useRef(null); const [value, setValue] = useState(''); const [isSubmitted, setIsSubmitted] = useState(false); const [errorMessage, setErrorMessage] = useState(''); const [successMessage, setSuccessMessage] = useState(''); const validate = () => { if (!value) { setSuccessMessage(''); setErrorMessage('Value is required'); inputRef.current.focus(); return; } else { setErrorMessage(''); setSuccessMessage('Success message!'); } }; useEffect(() => { if (isSubmitted) { validate(); } }, [value]); const onSubmit = (event) => { event.preventDefault(); validate(); setIsSubmitted(true); }; return ( <form onSubmit={onSubmit}> <V2TextInputArea label="Success message (useState)" value={value} onChange={(e) => setValue(e.target.value)} ref={inputRef} successMessage={successMessage} errorMessage={errorMessage} isRequired /> <V2Button type="submit" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </form> ); }; ``` ### Highlighted ```jsx render <Docs.FormCompatibilityWidget useForm useState /> ``` Use the `highlighted` prop to enable a distinct background color when fields are required. To supply this across all form input components using `useFormV2`/`V2FormProvider` you can provide `highlighted` to `V2FormProvider` as shown [here](/web/ui/form-provider-v2#highlighted). ```jsx live () => { const [value, setValue] = useState(''); return ( <V2TextInputArea label="Highlighted useState" value={value} isClearable onChange={(e) => setValue(e.target.value)} isRequired highlighted /> ); }; ``` ```jsx live () => { const form = useFormV2(); return ( <V2FormProvider state={form}> <V2TextInputArea label="Highlighted useForm" model="textForm" validators={{ required: true }} highlighted /> </V2FormProvider> ); }; ``` ## Max length Use the `maxLength` prop to limit the number of characters allowed in the input field. The default is `500`. ```jsx live () => { const form = useFormV2(); return ( <V2FormProvider state={form}> <V2TextInputArea label="Max Length" maxLength={4} model="maxLength" subText="Type to hit character limit" /> </V2FormProvider> ); }; ``` ## Max length threshold alerts Use the `alertThresholds` prop to specify an array of percentage thresholds (as decimals) at which to announce the percentage of characters used to screen readers. For example, passing `[0.25, 0.5, 0.75]` will announce when 25%, 50%, and 75% of the max length has been used. ```jsx live () => { const form = useFormV2(); return ( <V2FormProvider state={form}> <V2TextInputArea label="Max Length with Announcements" maxLength={20} model="maxLengthWithAnnouncements" displayMaxLength alertThresholds={[0.25, 0.5, 0.75]} subText="Type to get to character limit" /> </V2FormProvider> ); }; ``` ## Preserve whitespace To preserve leading or trailing whitespace in your inputs, set prop `preserveWhitespace` to `true`. ```jsx live () => { const form = useFormV2({ defaultValues: { textForm: ' Try adding some whitespace!', }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2TextInputArea label="V2TextInputArea Keep Whitespace" model="textForm" validators={{ required: true }} preserveWhitespace /> <V2Button type="submit" style={{ marginTop: 15 }}> Submit </V2Button> </V2FormProvider> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2TextInputArea" propTypeName="TextInputAreaProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2ClassesTable title="V2TextInputArea" classes={[TextInputAreaClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> ```jsx live () => { const form = useFormV2({ defaultValues: { textForm: 'Form Value', }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2TextInputArea label="Describe issue" model="textForm" subText="Be as specific as possible" errorMessage="Enter issue found" maxLength={100} alertThresholds={[0.5, 0.75]} validators={{ required: true }} /> <V2Button type="submit" style={{ marginTop: 15 }}> Submit </V2Button> </V2FormProvider> ); }; ``` #### Known BrAT issues - JAWS (prior to 2024) - ARIA settings including (aria-describedby, aria-required, aria-invalid) are not announced on textarea - Firefox / NVDA - Alerts (when reaching 50%, 75%, etc.) announce extra times - This does not occur using Chrome (with NVDA or JAWS) or Safari (MacOS with VO) </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={TextInputArea} keys={['textInputAreaV2']} /> ``` ```jsx render <Docs.ComponentTokensTable of={'Header'} keys={['inputHeaderV2']} /> ``` ```jsx render <Docs.ComponentTokensTable of={'Validation'} keys={['inputValidationV2']} /> ``` </Tab> --- id: text-input-area category: Forms title: TextInputArea description: Allows users to enter multi-line text into a UI. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=3697-25655 subDirectory: TextInputArea/v1 --- <Tab label="Overview"> ```jsx import { TextInputArea } from '@uhg-abyss/web/ui/TextInputArea'; ``` ```jsx sandbox { component: 'TextInputArea', inputs: [ { prop: 'placeholder', type: 'string', }, { prop: 'subText', type: 'string', }, { prop: 'maxLength', type: 'number', }, { prop: 'rows', type: 'number', }, { prop: 'hideLabel', type: 'boolean', }, { prop: 'isDisabled', type: 'boolean', }, { prop: 'isRequired', type: 'boolean', }, { prop: 'displayMaxLength', type: 'boolean', }, { prop: 'disableAutoSize', type: 'boolean', }, ], } () => { const [value, setValue] = useState('State Default Value'); return ( <TextInputArea label="TextInputArea Sandbox" value={value} onChange={(e) => setValue(e.target.value)} /> ); }; ``` ## useForm (recommended) Using the `useForm` hook for handling TextInputArea lets the DOM handle form data. ```jsx live () => { const form = useForm({ defaultValues: { textForm: 'Form Value', }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <TextInputArea label="TextInputArea useForm" model="textForm" validators={{ required: true }} /> <Button type="submit" style={{ marginTop: 15 }}> Submit </Button> </FormProvider> ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [value, setValue] = useState('State Default Value'); return ( <TextInputArea label="TextInputArea useState" value={value} onChange={(e) => setValue(e.target.value)} /> ); }; ``` ## Add elements inside input Use `inputRightElement` prop to add an element inside of the text input field. The recommended usage is for inserting icons. These are considered decorative and do not need to be exposed to screen readers. That said, please note that icons should _not_ provide any information that is not also conveyed in a screen-readable way. For example, an (!) icon to indicate errors needs to be accompanied by `aria-invalid`. If icons are used to convey additional information, use the `inputRightElementDescription` prop to provide a description for screen readers. See the [Validation](#validation) section below for an example on how to incorporate with validation and display error/success states with icons. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <TextInputArea label="Add Elements" placeholder="Placeholder Text" model="addElement" inputRightElement={<IconSymbol icon="check" size="20px" />} inputRightElementDescription="Checkmark Icon" /> </FormProvider> ); }; ``` ## Rows Use the `rows` prop to set the amount of rows displayed in the text area. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <TextInputArea rows={8} label="Rows" model="rows" /> </FormProvider> ); }; ``` ## Subtext Use the `subText` prop to display helpful text below the input field. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <TextInputArea label="Sub Text" model="subText" subText="Custom Sub Text" /> </FormProvider> ); }; ``` ## Error message Use the `errorMessage` prop to display a custom error message below the input field. Note: The errorMessage prop does not work with useForm and is only applicable within our form input components when useState is being utilized. See the [useForm Docs](/web/hooks/use-form#set-error) for example use cases with useForm. ```jsx live () => { const [value, setValue] = useState('Default Value'); return ( <TextInputArea label="Input With Error" errorMessage="Error Message" value={value} onChange={(e) => setValue(e.target.value)} /> ); }; ``` ## Descriptors display Use the `descriptorsDisplay` prop to set the orientation of the error message and subtext descriptor content. Available variants include 'column' and 'row'. The default is set to 'row'. Use the [FormProvider](/web/ui/form-provider#descriptors-display) and `descriptorsDisplay` to set the descriptors orientation across an entire form. ```jsx live () => { const [value, setValue] = useState(''); return ( <TextInputArea onChange={(e) => setValue(e.target.value)} value={value} label="Descriptors Display" subText="Subtext Message" errorMessage="Error Message" descriptorsDisplay="column" /> ); }; ``` ## Label Use the `label` prop to display a label above the input. To hide the input label set `hideLabel` to `true`. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <TextInputArea label="Custom Label" placeholder="Custom Label" model="custom-label" /> <TextInputArea label="Hidden Label" placeholder="Hidden Label" model="custom-hidden-label" hideLabel /> </FormProvider> ); }; ``` ## Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip) or a [Popover](/web/ui/popover). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <TextInputArea label="Default Helper" helper="This is a tooltip" model="helper-tooltip" /> <TextInputArea label="Custom Helper" helper={ <Popover title="Custom Helper" content="This is a popover with a custom icon" > <IconSymbol icon="help" variant="outlined" color="$success1" size="$sm" /> </Popover> } model="helper-custom" validators={{ required: true }} /> </FormProvider> ); }; ``` ## Disabled Set the `isDisabled` prop to `true` to disable the input field so users cannot enter a value. ```jsx live () => { const form = useForm({ defaultValues: { disabled: 'Disabled', }, }); return ( <FormProvider state={form}> <TextInputArea isDisabled={true} label="Disabled" model="disabled" /> </FormProvider> ); }; ``` ## Max length Use the `maxLength` prop to limit the number of characters allowed in the input field. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <TextInputArea label="Max Length" maxLength={4} model="maxLength" placeholder="Type to see character limit" /> </FormProvider> ); }; ``` ## Display max length Set the `displayMaxLength` prop to `true` to display the max length character counter. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <TextInputArea label="Display Max Length" maxLength={20} model="displayMaxLength" displayMaxLength placeholder="Type to see character limit" /> </FormProvider> ); }; ``` ## Max length threshold alerts Use the `alertThresholds` prop to specify an array of percentage thresholds (as decimals) at which to announce the percentage of characters used to screen readers. For example, passing `[0.25, 0.5, 0.75]` will announce when 25%, 50%, and 75% of the max length has been used. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <TextInputArea label="Max Length with Announcements" maxLength={20} model="maxLengthWithAnnouncements" displayMaxLength alertThresholds={[0.25, 0.5, 0.75]} placeholder="Type to see character limit" /> </FormProvider> ); }; ``` ## Disable auto sizing Set the `disableAutoSize` prop to `true` to disable auto sizing. ```jsx live () => { const [value, setValue] = useState( 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus sagittis sodales sapien. Donec vitae euismod leo. Suspendisse vel accumsan sapien. Aliquam ut magna convallis, malesuada velit vitae, pulvinar nulla. Suspendisse vitae tortor vulputate orci semper euismod mattis ut metus. Proin semper nulla id suscipit sollicitudin. Curabitur ac vestibulum orci, sed mollis augue. Etiam in sollicitudin ipsum, ut ultrices ante. Etiam et pulvinar tellus. Integer et accumsan dui, ac euismod lacus. Phasellus purus dui, euismod at ante eu, volutpat sodales turpis. Integer fermentum, sapien ut viverra tristique, urna nisi efficitur quam, a pulvinar ex leo eget liber' ); return ( <React.Fragment> <TextInputArea label="Disabled Auto Sizing" value={value} disableAutoSize onChange={(e) => setValue(e.target.value)} /> <TextInputArea label="Auto Sizing" value={value} onChange={(e) => setValue(e.target.value)} /> </React.Fragment> ); }; ``` ## Validation Use the validators prop to set rules for the field to be valid. ```jsx live () => { const form = useForm(); const { errors, isSubmitted, isSubmitSuccessful } = form.formState; const getIconProps = useCallback( (model) => { if (!isSubmitted) return {}; let iconProps = {}; if (!!errors[model]) { iconProps = { icon: 'error', color: '$error1', size: '18px' }; } if (isSubmitSuccessful) { iconProps = { icon: 'check', color: '$success1', size: '18px' }; } const isEmpty = Object.keys(iconProps).length === 0; return !isEmpty ? { inputRightElement: <IconSymbol {...iconProps} /> } : {}; }, [isSubmitted, isSubmitSuccessful] ); return ( <FormProvider state={form}> <TextInputArea label="Required Default Message" model="required" {...getIconProps('required')} validators={{ required: true }} /> <TextInputArea label="Required Custom Message" model="custom-required" validators={{ required: 'Custom Error Message' }} /> <Button type="submit" style={{ marginTop: 15 }}> Submit </Button> </FormProvider> ); }; ``` ## Highlighted Use the `highlighted` prop to enable the background color for the input. You can use `FormProvider` and `highlighted` to enable the color to appear if validation is required. ```jsx live () => { const [value, setValue] = useState(); return ( <TextInputArea label="Highlighted" value={value} onChange={(e) => setValue(e.target.value)} highlighted /> ); }; ``` ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit} highlighted> <TextInputArea label="FormProvider Highlighted" model="highlighted" validators={{ required: true }} /> <Button type="submit" style={{ marginTop: 15 }}> Submit </Button> </FormProvider> ); }; ``` ## Preserve whitespace To preserve leading or trailing whitespace in your inputs, set prop `preserveWhitespace` to `true`. ```jsx live () => { const form = useForm({ defaultValues: { textForm: 'Try adding some whitespace!', }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <TextInputArea label="TextInputArea Keep Whitespace" model="textForm" validators={{ required: true }} preserveWhitespace /> <Button type="submit" style={{ marginTop: 15 }}> Submit </Button> </FormProvider> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={TextInputArea} rows={[ { name: 'value', type: 'number | string', description: 'Value of the text area', }, { name: 'model', type: 'string', description: 'Unique identifier used for FormProvider', }, { name: 'validators', type: 'object', description: 'Rules for text area validation', }, { name: 'onChange', type: 'function', description: 'Callback fired everytime the value changes', }, { name: 'onFocus', type: 'function', description: 'Callback fired everytime the component is focused', }, { name: 'onBlur', type: 'function', description: 'Callback fired everytime the component is unfocused', }, { name: 'onKeyDown', type: 'function', description: 'Callback fired everytime a key is pressed while focused in the component', }, { name: 'onPaste', type: 'function', description: 'Callback fired everytime something is pasted into the component', }, { name: 'isDisabled', type: 'boolean', description: 'Flag to enable/disable the text area. If true, the text area will be disabled', }, { name: 'isRequired', type: 'boolean', description: 'Flag to require text', }, { name: 'hideLabel', type: 'boolean', description: 'Flag to hide label', }, { name: 'maxLength', type: 'number', description: 'Maximum amount of characters allowed in the text area', }, { name: 'displayMaxLength', type: 'boolean', description: 'Display the maximum length character counter', }, { name: 'disableAutoSize', type: 'boolean', description: 'Disable the auto size functionality', }, { name: 'subText', type: 'string', description: 'Text displayed below the text area', }, { name: 'errorMessage', type: 'string', description: 'Error message displayed below the text area', }, { name: 'descriptorsDisplay', type: '"row" | "column"', description: 'Set the orientation of descriptor content located below the text area', }, { name: 'rows', type: 'number', description: 'The number of rows displayed in the text area', }, { name: 'label', type: 'string', description: 'Set the label of the text area', }, { name: 'helper', type: 'node | string', description: 'Helper element next to label', }, { name: 'inputRightElement', type: 'ReactNode', description: 'Add element to right of inside text area', }, { name: 'inputRightElementDescription', type: 'string', description: 'Screen reader description for the right input element', }, { name: 'preserveWhitespace', type: 'boolean', description: 'Set to true to preserve leading and trailing whitespace', }, { name: 'alertThresholds', type: 'number[]', description: 'List of decimal thresholds for character count alerts when maxLength is used (ex: [.75] for an alert of 75% of characters used).', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={TextInputArea} rows={[ { name: 'text-input-area-root', description: 'TextInputArea root element', }, { name: 'text-input-area-label-wrapper', description: 'FormInput label wrapper. Contains label and max length label.', }, { name: 'text-input-area-label', description: 'FormInput label', }, { name: 'text-input-area-max-length-label', description: 'FormInput max length label', }, { name: 'text-input-area-input', description: 'FormInput', }, { name: 'text-input-area-input-descriptors', description: 'Descriptor for FormInput', }, { name: 'text-input-area-right-element-wrapper', description: 'Wrapper for right input element', }, { name: 'text-input-area-right-element', description: 'Text input area right element', }, { name: 'text-input-area-wrapper-container', description: 'Text input area container', }, ]} /> ``` </Tab> <Tab label="Accessibility"> ```jsx live () => { const form = useForm({ defaultValues: { textForm: 'Form Value', }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <TextInputArea label="Describe issue" model="textForm" subText="Be as specific as possible" errorMessage="Enter issue found" inputRightElement={ <IconMaterial icon="check" size="18px" title="Text is acceptable" isScreenReadable={true} /> } maxLength={100} displayMaxLength alertThresholds={[0.5, 0.75]} placeholder="description goes here" validators={{ required: true }} /> <Button type="submit" style={{ marginTop: 15 }}> Submit </Button> </FormProvider> ); }; ``` #### Known BrAT issues - JAWS (prior to 2024) - ARIA settings including (aria-describedby, aria-required, aria-invalid) are not announced on textarea - Firefox / NVDA - Alerts (when reaching 50%, 75%, etc.) announce extra times - This does not occur using Chrome (with NVDA or JAWS) or Safari (MacOS with VO) </Tab> --- id: theme-provider category: Providers title: ThemeProvider description: An Abyss component that passes the theme object down the component tree. --- # Theming Abyss theming supports changing colors, spacing, box-shadows, font families, font sizes and many other properties. Themes let you apply a consistent tone to your app. It allows you to customize all design aspects of your project in order to meet the specific needs of your business or brand. To configure the theme, wrap your app with a `ThemeProvider` component: ## ThemeProvider `ThemeProvider` relies on the context feature of React to pass the theme down to the components, so you need to make sure that `ThemeProvider` is a parent of the components you are trying to customize. ```jsx render <Docs.PropsTable of={ThemeProvider} rows={[ { name: 'children', type: 'node', description: 'Your component tree.', }, { name: 'theme', type: 'union: object | func', description: 'A theme object, usually the result of createTheme().', }, { name: 'brandAssetsCdn', type: 'string', description: 'A URL to provide a custom CDN for hosting brand assets handled by the Brandmark and IconBrand components', }, { name: 'includeBaseCss', type: 'boolean', description: `When set to false, the global base CSS and fonts will not be included.`, }, ]} /> ``` ## createTheme The `createTheme` function is used to create a theme object that can be passed to the `theme` prop on the `ThemeProvider`. This function takes one of three theme values, `'uhc | 'optum' | 'uhg' | 'abyss'` and an optional theme override object as arguments. For more information see the <BrandLink pathTemplate="/web/tools/create-theme-{brand}">createTheme</BrandLink> documentation page. ```jsx import { ThemeProvider } from '@uhg-abyss/web/ui/ThemeProvider'; import { createTheme } from '@uhg-abyss/web/tools/theme'; const theme = createTheme('uhc'); const App = () => { return <ThemeProvider theme={theme}>...</ThemeProvider>; }; ``` ## Related links - [Theming/Styling Overview](/web/developers/theming-styling) - <BrandLink pathTemplate="/web/tools/create-theme-{brand}"> createTheme Documentation </BrandLink> - <BrandLink pathTemplate="/web/tools/create-theme-{brand}#theme-overrides"> Theme Token Overrides </BrandLink> - [Styling with styled tool](/web/tools/styled) - [Styling with CSS Prop](/web/developers/theming-styling/#css-prop) --- id: time-input-v2 category: Forms title: V2TimeInput description: Capture time input from user. design: https://www.figma.com/design/a8XbEI7AmNb94mOBgYUB7y/v1.75.0-Web-Abyss-Global%E2%80%A8Component-Library?node-id=5860-379&m=dev subDirectory: TimeInput/v2 sourceIsTS: true --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="TimeInput" /> ``` ```jsx import { V2TimeInput } from '@uhg-abyss/web/ui/TimeInput'; ``` ```jsx sandbox { component: 'V2TimeInput', inputs: [ { prop: 'label', type: 'string', }, { prop: 'subText', type: 'string', }, { prop: 'errorMessage', type: 'string', }, { prop: 'successMessage', type: 'string', }, { prop: 'hideLabel', type: 'boolean', }, { prop: 'isClearable', type: 'boolean', }, { prop: 'isDisabled', type: 'boolean', }, { prop: 'highlighted', type: 'boolean', }, ] } () => { const [value, setValue] = useState(''); return ( <V2TimeInput label="TimeInput Sandbox" value={value} onChange={setValue} /> ); }; ``` ## Variants ### Input with time picker The default variant for `V2TimeInput` is an input field with a button to open a time picker. ```jsx live () => { const form = useFormV2({}); return ( <V2FormProvider state={form}> <V2TimeInput label="Input with time picker" model="input-with-time-picker" isClearable /> </V2FormProvider> ); }; ``` ### Input only Use the `inputOnly` prop when the time can be easily entered without a time picker. ```jsx live () => { const form = useFormV2({}); return ( <V2FormProvider state={form}> <V2TimeInput inputOnly label="Input only" model="input-only" isClearable inputLeftElement={{ element: ( <IconSymbol variant="outlined" icon="schedule" size="$web.semantic.sizing.icon.utility.sm" color="$web.semantic.color.icon.interactive.rest.secondary" /> ), description: 'Schedule appointment', }} /> </V2FormProvider> ); }; ``` ## useForm (Recommended) ```jsx render <Docs.FormMessage /> ``` ```jsx render <Docs.FormDisclaimer /> ``` ```jsx live () => { const form = useFormV2({ defaultValues: { 'time-input': '01:00', }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2TimeInput isClearable label="TimeInput useForm" model="time-input" validators={{ required: true }} /> <V2Button type="submit" style={{ marginTop: 15 }}> Submit </V2Button> </V2FormProvider> ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [value, setValue] = useState('13:00'); console.log('useState Value', value); return ( <V2TimeInput label="TimeInput useState" value={value} onChange={setValue} isClearable onClear={() => { setValue(''); return console.log('input cleared'); }} onFocus={(e) => console.log('focused', e)} onBlur={(e) => console.log('blurred', e)} /> ); }; ``` ## Format Use the `format` prop to change the time format for the input. The possible values are `'12'` (the default) and `'24'`. ```jsx live () => { const [value, setValue] = useState('13:00'); console.log('useState Value', value); return ( <V2TimeInput label="24-Hour Format" value={value} onChange={setValue} format="24" /> ); }; ``` ## Display Properties ### Label Use the `label` prop to display a label above the input. To hide the input label, set `hideLabel` to `true`. Use `isRequired` and `isOptional` for further customization. Note: If using `useForm`, do not use `isRequired`. The same functionality can be achieved with `required: true` in `validators`. ```jsx live () => { const form = useFormV2(); return ( <V2FormProvider state={form}> <V2TimeInput label="Custom Label" model="custom-label" /> <V2TimeInput label="Hidden Label" model="custom-hidden-label" hideLabel /> <V2TimeInput label="Required Label" model="custom-req-label" isRequired /> <V2TimeInput label="Optional Label" model="custom-opt-label" isOptional /> </V2FormProvider> ); }; ``` ### Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip-v2) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip-v2) or a [Popover](/web/ui/popover-v2). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip-v2/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live () => { const form = useFormV2(); return ( <V2FormProvider state={form}> <V2TimeInput label="Default Helper" helper="This is a tooltip" model="helper-tooltip" /> <V2TimeInput label="Custom Helper" helper={ <V2Popover title="Custom Helper" content="This is a popover with a custom icon" > <IconSymbol icon="help" variant="outlined" color="$core.color.brand-60" size="$md" /> </V2Popover> } model="helper-custom" validators={{ required: true }} /> </V2FormProvider> ); }; ``` ### Subtext Use the `subText` prop to display helpful information related to the input field. The prop accepts either a string or an object of the form: ```ts { text: string; position: 'above' | 'below'; } ``` The `position` property determines where the subtext will be displayed in relation to the input field. The default value is `'below'`. ```jsx live () => { const form = useFormV2(); return ( <V2FormProvider state={form}> <Layout.Stack space={12} grow> <V2TimeInput label="Regular Subtext" model="regular-subtext" subText="Subtext with a regular string" /> <V2TimeInput label="Subtext passed as an object" model="above-subtext" subText={{ text: 'Subtext passed above the input', position: 'above', }} /> <V2TimeInput label="Subtext passed as an object" model="below-subtext" subText={{ text: 'Subtext passed below the input', position: 'below', }} /> </Layout.Stack> </V2FormProvider> ); }; ``` ### Width Use the `width` prop to set the width of the input field. ```jsx live () => { const form = useFormV2(); return ( <V2FormProvider state={form}> <V2TimeInput label="Width Default" model="width1" isClearable /> <V2TimeInput width="75%" label="Width 75%" model="width2" isClearable /> <V2TimeInput width="335px" model="width3" label="Width 335px" isClearable /> </V2FormProvider> ); }; ``` ### Left Element Use the `inputLeftElement` prop to add an element inside the text input field. The recommended usage is for inserting icons. The prop accepts an object with the following properties: - `element`: The element to be displayed inside the input field. - `description`: An optional string that describes the purpose of the element for screen readers. These are considered decorative and do not need to be exposed to screen readers. That said, please note that icons should _not_ provide any information that is not also conveyed in a screen-readable way. For example, an exclamation mark (!) icon to indicate errors needs to be accompanied by `aria-invalid`. If the icon is used to convey additional information, use the `inputLeftElement.description` prop to provide a description for screen readers. Note: The recommended usage is when using the `inputOnly` prop. ```jsx live () => { const form = useFormV2({ defaultValues: { 'left-element': '13:00', }, }); return ( <V2FormProvider state={form}> <V2TimeInput inputOnly label="Left Element" model="left-element" isClearable inputLeftElement={{ element: ( <IconSymbol icon="bedtime" variant="outlined" size="$web.semantic.sizing.icon.utility.sm" color="$web.semantic.color.icon.interactive.rest.secondary" /> ), description: 'Schedule appointment', }} /> </V2FormProvider> ); }; ``` ## Validation ### Validators (useFormV2) ```jsx render <Docs.FormCompatibilityWidget useForm /> ``` Use the `validators` prop to set validation rules for the field when using `useFormV2`. See the examples below for implementation on various types of validation. Note: The default error message when `required` is `true` is minimally acceptable for accessibility. It is highly recommended to customize it to be more specific to the use of the field and form. ```jsx live () => { const form = useFormV2(); const marginBottom = { 'abyss-time-input-root': { marginBottom: '20px' }, }; const minutesIncrement = 15; return ( <V2FormProvider state={form}> <V2TimeInput css={marginBottom} label="Required Default Message" model="required" validators={{ required: true }} /> <V2TimeInput css={marginBottom} label="Required Custom Message" model="custom-required" validators={{ required: 'Custom Error Message' }} /> <V2TimeInput label="Custom Validators" model="validate" subText={`Enter in ${minutesIncrement} minute increments`} validators={{ required: true, validate: { incrementAllowed: (v) => { const minuteValue = dayjs(v, 'hh:mm').minute(); if (minuteValue % minutesIncrement === 0) return true; return `Only ${minutesIncrement} minute increments are allowed`; }, }, }} /> <V2Button type="submit" style={{ marginTop: 15 }}> Submit </V2Button> </FormProvider> ); }; ``` ### Error message (useState) ```jsx render <Docs.FormCompatibilityWidget useState /> ``` Use the `errorMessage` prop to display a custom error message below the input field when using `useState`. ```jsx live () => { const [value, setValue] = useState('13:00'); return ( <V2TimeInput label="Error Message" value={value} onChange={setValue} errorMessage="Custom error message" /> ); }; ``` ### Success message ```jsx render <Docs.FormCompatibilityWidget useForm useState /> ``` Use the `successMessage` prop to display a custom success message below the input field. To provide a single success message across all form input components using `useFormV2`/`V2FormProvider`, you can provide `successMessage` to `V2FormProvider` as shown [here](/web/ui/form-provider-v2#successmessage). ```jsx live () => { const form = useFormV2(); const onSubmit = (data) => { console.log(data); }; const minutesIncrement = 15; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2TimeInput label="Success Message (useForm)" model="validate" successMessage="Time is valid!" subText={`Enter in ${minutesIncrement} minute increments`} validators={{ required: true, validate: { incrementAllowed: (v) => { const minuteValue = dayjs(v, 'hh:mm').minute(); if (minuteValue % minutesIncrement === 0) return true; return `Only ${minutesIncrement} minute increments are allowed`; }, }, }} /> <Layout.Space /> <V2Button type="submit">Submit</V2Button> </V2FormProvider> ); }; ``` ```jsx live () => { const inputRef = useRef(null); const [value, setValue] = useState(''); const [isSubmitted, setIsSubmitted] = useState(false); const [errorMessage, setErrorMessage] = useState(''); const [successMessage, setSuccessMessage] = useState(''); const minutesIncrement = 15; // Change this to your desired increment const validateTime = () => { if (!value) { setErrorMessage('Select a time'); setSuccessMessage(''); inputRef.current.focus(); return; } // Assumes value is in "HH:mm" format const minuteValue = dayjs(value, 'HH:mm', true).minute(); if (isNaN(minuteValue)) { setErrorMessage('Provide a valid time in HH:mm format'); setSuccessMessage(''); inputRef.current.focus(); return; } if (minuteValue % minutesIncrement === 0) { setErrorMessage(''); setSuccessMessage( `Time is valid and in ${minutesIncrement} minute increments!` ); } else { setErrorMessage(`Only ${minutesIncrement} minute increments are allowed`); setSuccessMessage(''); inputRef.current.focus(); } }; useEffect(() => { if (isSubmitted) { validateTime(); } }, [value]); const onSubmit = (e) => { e.preventDefault(); validateTime(); setIsSubmitted(true); }; return ( <form onSubmit={onSubmit}> <V2TimeInput isRequired label="Sucess Message (useState)" value={value} onChange={setValue} ref={inputRef} successMessage={successMessage} errorMessage={errorMessage} /> <Layout.Space /> <V2Button type="submit">Submit</V2Button> </form> ); }; ``` ### Highlighted ```jsx render <Docs.FormCompatibilityWidget useForm useState /> ``` Use the `highlighted` prop to enable a distinct background color when fields are required. To supply this across all form input components using `useFormV2`/`V2FormProvider` you can provide `highlighted` to `V2FormProvider` as shown [here](/web/ui/form-provider-v2#highlighted). ```jsx live () => { const form = useFormV2(); return ( <V2FormProvider state={form}> <V2TimeInput label="Highlighted useForm" model="textForm" isClearable validators={{ required: true }} highlighted /> </V2FormProvider> ); }; ``` ```jsx live () => { const [value, setValue] = useState(''); return ( <V2TimeInput label="Highlighted useState" value={value} onChange={setValue} isRequired highlighted /> ); }; ``` ### Validation below menu ```jsx render <Docs.FormCompatibilityWidget useForm useState /> ``` Set the `validationBelowMenu` prop to `true` to relocate the error and success message validation to below the menu, when open. The default is `false` and the validation message will always remain displayed below the selection container, even when the calendar is open. ```jsx live-in-view () => { const [value, setValue] = useState(); return ( <V2TimeInput label="Validation Below Menu" value={value} onChange={setValue} isClearable isRequired errorMessage="Select a time" validationBelowMenu /> ); }; ``` ## Interactivity ### Clearable Set the `isClearable` prop to `true` to display a clear button in the input field. The optional `onClear` callback prop can be used to trigger additional actions when the clear button is clicked. ```jsx live () => { const form = useFormV2({ defaultValues: { 'time-input': '01:00', }, }); return ( <V2FormProvider state={form}> <V2TimeInput label="Clearable" model="time-input" isClearable={true} onClear={() => console.log('input cleared')} /> </V2FormProvider> ); }; ``` ### Disabled Set the `isDisabled` prop to `true` to disable the input field, preventing user interaction. The input will still display the current value, but users cannot change it. ```jsx live () => { const form = useFormV2({ defaultValues: { 'time-input': '01:00', }, }); return ( <V2FormProvider state={form}> <V2TimeInput label="Disabled" model="time-input" isDisabled /> </V2FormProvider> ); }; ``` ### Enable outside scroll Set the `enableOutsideScroll` prop to `true` to allow the page to be scrolled while the calendar is open. The default value is `false`. ```jsx live () => { const form = useFormV2({ defaultValues: { 'time-input': '01:00', }, }); return ( <V2FormProvider state={form}> <V2TimeInput label="Scrollable Outside" model="time-input" enableOutsideScroll /> </V2FormProvider> ); }; ``` ## Responsiveness On screens less than 360px wide, the picker will be placed in a full-screen takeover instead of a popup. Resize the window and open the picker to see the change! ```jsx live () => { const form = useFormV2({ defaultValues: { 'time-input': '01:00', }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2TimeInput label="TimeInput useForm" model="time-input" validators={{ required: true }} isClearable /> <V2Button type="submit" style={{ marginTop: 15 }}> Submit </V2Button> </V2FormProvider> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2TimeInput" propTypeName="TimeInputProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2ClassesTable title="V2TimeInput" classes={[TimeInputClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> V2 Time input implements a simple group (`<fieldset>`) of three spin buttons for hours, minutes, and AM/PM. This makes the time picker dialog "redundant and unnecessary." To avoid the potential confusion and unnecessary redundant entry, the "Choose time" button does not receive keyboard focus. ```jsx live () => { const form = useFormV2(); const minutesIncrement = 15; return ( <V2FormProvider state={form}> <V2TimeInput label="Entry time" model="validate" highlighted inputLeftElement={{ element: ( <IconSymbol icon="clock_loader_10" variant="outlined" size="$web.semantic.sizing.icon.utility.sm" color="$web.semantic.color.icon.interactive.rest.secondary" /> ), description: 'Schedule appointment', }} subText={`Use ${minutesIncrement} minute increments`} successMessage="Time is acceptable" errorMessage="Invalid time" isClearable isRequired validators={{ required: true, validate: { incrementAllowed: (v) => { const minuteValue = dayjs(v, 'hh:mm').minute(); if (minuteValue % minutesIncrement === 0) return true; return `Time is not in ${minutesIncrement} minute increments`; }, }, }} /> <V2Button type="submit" style={{ marginTop: 15 }}> Submit </V2Button> </V2FormProvider> ); }; ``` ```jsx render <Docs.AccessibilityTable title="Time Entry Keyboard Interactions" rows={[ { name: 'Tab', description: 'Moves focus to next V2TimeInput field, clear button or exits component', }, { name: 'Shift + Tab', description: 'Moves focus to previous V2TimeInput field or exits component', }, { name: 'Up Arrow', description: 'Increments current hour or minute field; toggles AM / PM', }, { name: 'Down Arrow', description: 'Decrements current hour or minute field; toggles AM / PM', }, ]} /> ``` </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={TimeInput} keys={['timeInputV2', 'inputV2']} /> ``` ```jsx render <Docs.ComponentTokensTable of={'TimePicker'} keys={['timePickerV2']} /> ``` ```jsx render <Docs.ComponentTokensTable of={'Header'} keys={['inputHeaderV2']} /> ``` ```jsx render <Docs.ComponentTokensTable of={'Validation'} keys={['inputValidationV2']} /> ``` </Tab> --- id: time-input category: Forms title: TimeInput description: Capture time input from user. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=5502-26796 subDirectory: TimeInput/v1 --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="TimeInput" /> ``` ```jsx import { TimeInput } from '@uhg-abyss/web/ui/TimeInput'; ``` ```jsx sandbox { component: 'TimeInput', inputs: [ { prop: 'subText', type: 'string', }, { prop: 'errorMessage', type: 'string', }, { prop: 'hideLabel', type: 'boolean', }, { prop: 'isDisabled', type: 'boolean', }, { prop: 'highlighted', type: 'boolean', defaultValue: false, }, { prop: 'minutesIncrement', type: 'string', }, { prop: 'format', type: 'select', options: [ { label: '12', value: '12' }, { label: '24', value: '24' }, ] }, ] } () => { const [value, setValue] = useState(null); return ( <TimeInput label="TimeInput Sandbox" value={value} onChange={setValue} /> ); }; ``` ## useForm (recommended) Using the `useForm` hook for handling text input lets the DOM handle form data. ```jsx live () => { const form = useForm({ defaultValues: { 'time-input': '01:00', }, }); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <TimeInput isClearable label="TimeInput useForm" model="time-input" validators={{ required: true }} /> <Button type="submit" style={{ marginTop: 15 }}> Submit </Button> </FormProvider> ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [value, setValue] = useState('13:00'); console.log('useState Value', value); return ( <TimeInput label="TimeInput useState" value={value} onChange={setValue} isClearable onClear={() => setValue('')} /> ); }; ``` ## Format Use the `format` prop to change from 12 to 24 hour time format. The default is `12`. ```jsx live () => { const [value, setValue] = useState('13:00'); console.log('useState Value', value); return ( <TimeInput label="TimeInput Format" value={value} onChange={setValue} format="24" /> ); }; ``` ## Minutes increment Use the `minutesIncrement` prop to update the minute increment options that are available for selection within the time picker. The default is `5`. NOTE: this setting does not provide any validation when using the input field to enter the time value. If you'd like to add custom validation to only allow certain increments please see the Custom Validators example from the [Validation](#validation) section below. ```jsx live () => { const [value, setValue] = useState('13:00'); console.log('useState Value', value); return ( <TimeInput label="TimeInput Format" value={value} onChange={setValue} minutesIncrement="30" /> ); }; ``` ## Add elements inside input Use the `inputLeftElement` and `inputRightElement` props to add elements to the inside of the time input field. The recommended usage is for inserting icons. These are considered decorative and do not need to be exposed to screen readers. That said, please note that icons should _not_ provide any information that is not also conveyed in a screen-readable way. For example, an (!) icon to indicate errors needs to be accompanied by `aria-invalid`. If icons are used to convey additional information, use the `inputLeftElementDescription` and `inputRightElementDescription` props to provide a description for screen readers. See the [Validation](#validation) section below for an example on how to incorporate with validation and display error/success states with icons. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <TimeInput label="TimeInput Inside Elements" model="time-input-elements" validators={{ required: true }} inputLeftElement={ <IconSymbol icon="assignment" size="20px" color="$gray6" /> } inputRightElement={ <IconSymbol icon="check" size="20px" color="$success1" /> } inputLeftElementDescription="Clipboard icon" inputRightElementDescription="Checkmark icon" /> </FormProvider> ); }; ``` ## Subtext Use the `subText` prop to display helpful text below the time input field. By default it displays `Time Format: hh:mm`. ```jsx live () => { const [value, setValue] = useState(null); return ( <TimeInput label="TimeInput SubText" value={value} onChange={setValue} subText="Custom Sub Text" /> ); }; ``` ## Error message Use the `errorMessage` prop to display a custom error message below the time input field. Note: The errorMessage prop does not work with useForm and is only applicable within our form input components when useState is being utilized. See the [useForm Docs](/web/hooks/use-form#set-error) for example use cases with useForm. ```jsx live () => { const [value, setValue] = useState(null); return ( <TimeInput label="TimeInput Error Message" value={value} onChange={setValue} errorMessage="Custom Error Message" /> ); }; ``` ## Descriptors display Use the `descriptorsDisplay` prop to set the orientation of the error message and subtext descriptor content. Available variants include 'column' and 'row'. The default is set to 'row'. Use the [FormProvider](/web/ui/form-provider#descriptors-display) and `descriptorsDisplay` to set the descriptors orientation across an entire form. ```jsx live () => { const [value, setValue] = useState(null); return ( <TimeInput label="TimeInput Descriptors Display" value={value} onChange={setValue} subText="Subtext Message" errorMessage="Error Message" descriptorsDisplay="column" /> ); }; ``` ## Label Use the `label` prop to display a label above the input. To hide the input label set `hideLabel` to `true`. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <TimeInput css={{ 'abyss-time-input-root': { marginBottom: '20px' } }} model="time-input" label="TimeInput Custom Label" /> <TimeInput model="time-input-2" label="TimeInput Hidden Label" hideLabel /> </FormProvider> ); }; ``` ## Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip) or a [Popover](/web/ui/popover). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <TimeInput label="Default Helper" helper="This is a tooltip" model="helper-tooltip" /> <TimeInput label="Custom Helper" helper={ <Popover title="Custom Helper" content="This is a popover with a custom icon" > <IconSymbol icon="help" variant="outlined" color="$success1" size="$sm" /> </Popover> } model="helper-custom" validators={{ required: true }} /> </FormProvider> ); }; ``` ## Disabled Set the `isDisabled` prop to `true` to disable the input field so users cannot enter a value. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <TimeInput label="TimeInput Disabled" model="time-input" isDisabled /> <Button type="submit" style={{ marginTop: 15 }}> Submit </Button> </FormProvider> ); }; ``` ## Validation Use the `validators` prop to set rules for the field to be valid. ```jsx live () => { const form = useForm(); const { errors, isSubmitted, isSubmitSuccessful } = form.formState; const getIconProps = useCallback( (model) => { if (!isSubmitted) return null; let iconProps = {}; if (!!errors[model]) { iconProps = { icon: 'error', color: '$error1', size: '18px' }; } if (isSubmitSuccessful) { iconProps = { icon: 'check', color: '$success1', size: '18px' }; } return { inputRightElement: <IconSymbol {...iconProps} /> }; }, [isSubmitted, isSubmitSuccessful] ); const marginBottom = { 'abyss-time-input-root': { marginBottom: '20px' }, }; const minutesIncrement = 15; return ( <FormProvider state={form}> <TimeInput css={marginBottom} label="Required Default Message" model="required" {...getIconProps('required')} validators={{ required: true }} /> <TimeInput css={marginBottom} label="Required Custom Message" model="custom-required" validators={{ required: 'Custom Error Message' }} /> <TimeInput label="Custom Validators" model="validate" minutesIncrement={minutesIncrement} subText={`Enter in ${minutesIncrement} minute increments`} validators={{ required: true, validate: { incrementAllowed: (v) => { const minuteValue = dayjs(v, 'hh:mm').minute(); if (minuteValue % minutesIncrement === 0) return true; return `Only ${minutesIncrement} minute increments are allowed`; }, }, }} /> <Button type="submit" style={{ marginTop: 15 }}> Submit </Button> </FormProvider> ); }; ``` ## Highlighted Use the `highlighted` prop to enable the background color for the input. You can use `FormProvider` and `highlighted` to enable the color to appear if validation is required. ```jsx live () => { const [value, setValue] = useState(null); return ( <TimeInput label="TimeInput Highlighted" value={value} onChange={setValue} highlighted /> ); }; ``` ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('data', data); }; return ( <FormProvider state={form} onSubmit={onSubmit} highlighted> <TimeInput label="FormProvider Highlighted" model="highlighted" validators={{ required: true }} /> <Button type="submit" style={{ marginTop: 15 }}> Submit </Button> </FormProvider> ); }; ``` ## Width Use the `width` prop to set the width of the input field. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <TimeInput label="Width Default" model="width-1" subText="Default Width" /> <TimeInput width="75%" label="Width 75%" model="width-2" subText="Width Set To 75%" /> <TimeInput width="335px" model="width-3" label="Width 335px" subText="Width Set To 335px" /> </FormProvider> ); }; ``` ## Enable outside scroll Set the `enableOutsideScroll`prop to`true` to enable scroll outside of the time input component while the time picker is open. Default is set to `false`. ```jsx live () => { const [value, setValue] = useState(null); return ( <TimeInput label="TimeInput Enable Outside Scroll" value={value} onChange={setValue} enableOutsideScroll /> ); }; ``` ## Clearable Use the `isClearable` prop to include a clearable button for TimeInput. By default, this is set to false. Note that if you are using `useState`, you will need to pass the `onClear` prop as well to handle clearing the data when the clear button is pressed. ```jsx live () => { const form = useForm({ defaultValues: { 'time-input': '01:00', }, }); return ( <FormProvider state={form}> <TimeInput isClearable label="Clearable (with useForm)" model="time-input" /> </FormProvider> ); }; ``` ```jsx live () => { const [value, setValue] = useState('01:00'); return ( <TimeInput label="Clearable (with useState)" value={value} onChange={setValue} isClearable onClear={() => setValue('')} /> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={TimeInput} rows={[ { name: 'format', type: '"12" | "24"', description: 'Sets to either 12 or 24 hour format', }, { name: 'minutesIncrement', type: 'string', description: 'Sets the minute increment of options that will available within the time picker', }, { name: 'label', type: 'string', description: 'Label for time input field', }, { name: 'helper', type: 'node | string', description: 'Helper element next to label', }, { name: 'isDisabled', type: 'boolean', description: 'Flag to enable/disable the input. If true, the input will be disabled', }, { name: 'value', type: 'string', description: 'Value of the time input. Must be a string in the format of "hh:mm"', }, { name: 'onChange', type: 'function', description: 'Callback fired every time the value changes', }, { name: 'onFocus', type: 'function', description: 'Callback fired every time the component is focused', }, { name: 'onBlur', type: 'function', description: 'Callback fired every time the component is unfocused', }, { name: 'width', type: 'string', description: 'Width of the input field', }, { name: 'subText', type: 'string', description: 'Set the text displayed below the time input field', default: 'Time Format: hh:mm', }, { name: 'errorMessage', type: 'string', description: 'Set the error message to be displayed below the time input field', }, { name: 'descriptorsDisplay', type: '"row" | "column"', description: 'Set the orientation of descriptor content located below the time input field', }, { name: 'hideLabel', type: 'boolean', description: 'Flag to show or hide label', }, { name: 'enableOutsideScroll', type: 'boolean', description: 'Flag to enable scrolling when the time picker is open', }, { name: 'inputLeftElement', type: 'ReactNode', description: 'Add element to left of inside time input', }, { name: 'inputRightElement', type: 'ReactNode', description: 'Add element to right of inside time input', }, { name: 'inputLeftElementDescription', type: 'string', description: 'Screen reader description for the left input element', }, { name: 'inputRightElementDescription', type: 'string', description: 'Screen reader description for the right input element', }, { name: 'isClearable', type: 'boolean', description: 'Add clear button inside time input', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={TimeInput} rows={[ { name: 'time-input-container', description: 'Container element', }, { name: 'time-input-picker-wrapper', description: 'Time picker dialog wrapper', }, { name: 'time-input-root', description: 'Time input root', }, { name: 'time-input-label', description: 'Time input label', }, { name: 'time-input-wrapper', description: 'Time input and icon wrapper', }, { name: 'time-input-left-element-wrapper', description: 'Time input wrapper for left element', }, { name: 'time-input-left-element', description: 'Time input content for left element', }, { name: 'time-input-right-element-wrapper', description: 'Time input wrapper for right element', }, { name: 'time-input-right-element', description: 'Time input content for right element', }, { name: 'time-input-input-container', description: 'Time input container', }, { name: 'time-input-hour-input', description: 'Hours text input', }, { name: 'time-input-minute-input', description: 'Minutes text input', }, { name: 'time-input-am-pm-input', description: 'AM/PM text input', }, { name: 'time-input-picker-button', description: 'Time picker open button', }, { name: 'time-input-picker-button-icon', description: 'Time picker open button icon', }, { name: 'time-input-descriptors', description: 'Time input descriptors', }, { name: 'time-input-picker-container', description: 'Time picker container', }, { name: 'time-input-picker-column-group-container', description: 'Time picker column group container', }, { name: 'time-input-picker-column-container', description: 'Time picker column container', }, { name: 'time-input-picker-separator', description: 'Time picker colon separator', }, { name: 'time-input-picker-decrease-hours-button', description: 'Time picker decrease hours button', }, { name: 'time-input-picker-increase-hours-button', description: 'Time picker increase hours button', }, { name: 'time-input-picker-decrease-minutes-button', description: 'Time picker decrease minutes button', }, { name: 'time-input-picker-increase-minutes-button', description: 'Time picker increase minutes button', }, { name: 'time-input-picker-arrow-button', description: 'Time picker arrow button', }, { name: 'time-input-picker-arrow-button-icon', description: 'Time picker arrow button icon', }, { name: 'time-input-picker-hours-option-list', description: 'Time picker hours option list', }, { name: 'time-input-picker-minutes-option-list', description: 'Time picker minutes option list', }, { name: 'time-input-picker-option-list', description: 'Time picker option list', }, { name: 'time-input-picker-option-item', description: 'Time picker option list item', }, { name: 'time-input-picker-option-item-content', description: 'Time picker option list item content', }, { name: 'time-input-picker-am-pm-toggle', description: 'Time picker AM/PM toggle', }, { name: 'time-input-picker-am-tab', description: 'Time picker AM toggle tab', }, { name: 'time-input-picker-pm-tab', description: 'Time picker PM toggle tab', }, { name: 'time-input-picker-portal-container', description: 'Time picker portal container', }, ]} /> ``` </Tab> <Tab label="Accessibility"> The example below includes a time input field and a button that opens a time picker which implements the dialog design pattern. The dialog contains a list of hour and minute options, decrease/increase buttons and AM/PM toggle tabs that enable the user to select the desired time. Choosing from the time picker populates the time input field. When the dialog is opened, if the input field is empty, then a time of "1:00am" (12 hour format) or "00:00" (24 hour format) is set and the selected hour option is focused. Otherwise, the focus is placed on the hour option that matches the value of the time input field. ```jsx live () => { const form = useForm(); const { errors, isSubmitted, isSubmitSuccessful } = form.formState; const getIconProps = useCallback( (model) => { if (!isSubmitted) return null; let iconProps = {}; if (!!errors[model]) { iconProps = { icon: 'error', color: '$error1', size: '18px' }; } if (isSubmitSuccessful) { iconProps = { icon: 'check', color: '$success1', size: '18px' }; } return { inputRightElement: <IconSymbol {...iconProps} /> }; }, [isSubmitted, isSubmitSuccessful] ); const marginBottom = { 'abyss-time-input-root': { marginBottom: '20px' }, }; const minutesIncrement = 10; return ( <FormProvider state={form}> <TimeInput label="Entry time" model="validate" minutesIncrement={minutesIncrement} subText={`Use ${minutesIncrement} minute increments`} isClearable validators={{ required: true, validate: { incrementAllowed: (v) => { const minuteValue = dayjs(v, 'hh:mm').minute(); if (minuteValue % minutesIncrement === 0) return true; return `Only ${minutesIncrement} minute increments are allowed`; }, }, }} /> <Button type="submit" style={{ marginTop: 15 }}> Submit </Button> </FormProvider> ); }; ``` <h3> Reduced Motion </h3> Animations and transitions that have been changed when a user has `prefers-reduced-motion` set to `reduced`: - Transition when switching between AM and PM is removed - The time picker no longer has the automatic scroll to top upon selection ```jsx render <div style={{ marginTop: '25px' }}> <Docs.AccessibilityTable title="Choose Time Button" rows={[ { name: 'Space', description: 'Open the time picker dialog. Move focus to selected hour.', }, { name: 'Enter', description: 'Open the time picker dialog. Move focus to selected hour.', }, ]} /> </div> ``` ```jsx render <Docs.AccessibilityTable title="Time Picker Dialog" rows={[ { name: 'Esc', description: 'Closes the dialog and returns focus to the Choose Time button', }, { name: 'Tab', description: 'Moves focus to next element in the dialog Tab sequence', }, { name: 'Shift + Tab', description: 'Moves focus to previous element in the dialog Tab sequence', }, ]} /> ``` ```jsx render <Docs.AccessibilityTable title="Time Picker Dialog: Increase/Decrease Buttons" rows={[ { name: 'Space', description: 'Change the hour or minute selection up or down by one option', }, ]} /> ``` ```jsx render <Docs.AccessibilityTable title="Time Picker Dialog: Hour/Minutes List" rows={[ { name: 'Enter', description: 'Close the dialog, and move focus to the Choose Time button', }, { name: 'Up Arrow', description: 'Moves focus and selection up one option from the currently selected hour or minute', }, { name: 'Down Arrow', description: 'Moves focus and selection down one option from the currently selected hour or minute', }, ]} /> ``` ```jsx render <Docs.AccessibilityTable title="Time Picker Dialog: AM/PM Toggle Tabs" rows={[ { name: 'Enter', description: 'Close the dialog, and move focus to the Choose Time button', }, { name: 'Arrow Right', description: 'Moves focus and selection to the option to the right', }, { name: 'Arrow Left', description: 'Moves focus and selection to the option to the left', }, ]} /> ``` </Tab> --- id: timeline-v2 category: Content title: V2Timeline description: Displays a list of content in chronological order. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=11281-2384 subDirectory: Timeline/v2 sourceIsTS: true --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="Timeline"></Docs.V2MigrationBanner> ``` ```jsx import { V2Timeline } from '@uhg-abyss/web/ui/Timeline'; ``` ```jsx sandbox { component: 'V2Timeline', inputs: [ { prop: 'type', type: 'select', options: [ { label: 'Card', value: 'card' }, { label: 'Simple', value: 'simple' }, ] }, { prop: 'title', type: 'string', defaultValue: 'Timeline history', }, { prop: 'activeStep', type: 'number', }, { prop: 'activeStepCompletionState', type: 'select', options: [ { label: 'In Progress', value: 'in-progress' }, { label: 'Completed', value: 'completed' }, ], defaultValue: 'in-progress', }, ], } () => { return ( <V2Timeline type="card" activeStep={1} > <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-05-30').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-05-31').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-06-01').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-06-02').format('MM/DD/YYYY')} /> </V2Timeline> ); }; ``` ## Steps Use the `V2Timeline.Step` subcomponent to define each step in the Timeline. The steps are rendered in the same order they are defined, so the first child will be the first step, the second child will be the second step, and so on. This section covers the props available for `V2Timeline.Step`. ### Title Use the `title` prop to set the title of the step. This prop is required. ```jsx live () => { return ( <V2Timeline activeStep={1}> <V2Timeline.Step title="Lorem ipsum" date={dayjs('2025-05-30').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Dolor sit" date={dayjs('2025-05-31').format('MM/DD/YYYY')} /> </V2Timeline> ); }; ``` ### Date Use the `date` prop to set the date of the step. This prop accepts a string. The examples on this page use [Day.js](/web/tools/dayjs) to format the dates, but teams are free to use any library they wish. ```jsx live () => { return ( <V2Timeline activeStep={1}> <V2Timeline.Step title="Lorem ipsum" date={dayjs('2025-05-30').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Dolor sit" /> </V2Timeline> ); }; ``` ### Hide completion state Use the `hideCompletionState` prop to hide the completion state below the title. Note that the state will still be read by screen readers for accessibility purposes. ```jsx live () => { return ( <V2Timeline activeStep={2}> <V2Timeline.Step title="Lorem ipsum" date={dayjs('2025-05-30').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Dolor sit" date={dayjs('2025-05-31').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Amet consectetur" hideCompletionState date={dayjs('2025-06-01').format('MM/DD/YYYY')} /> </V2Timeline> ); }; ``` ### Status Use the `status` prop to set the status of the step. The available statuses are `'neutral'`, `'info'`, `warning'`, and `'error'`. The default value is `'neutral'`. Note: Only the active step will change appearance based on the `status`. Additionally, if `type` is set to `'card'`, the card will change appearance based on the `status` of the active step. It is recommended to include `ariaText` when using the `status` prop to ensure that the status is accessible to screen reader users, particularly when not using the `'neutral'` status. The value of this prop will be set as the title for the status icon. ```jsx live () => { const [step2Status, setStep2Status] = useState('neutral'); const [step2AriaText, setStep2AriaText] = useState(''); return ( <Layout.Stack grow> <Layout.Group> <V2Button onClick={() => { setStep2Status('neutral'); setStep2AriaText(''); }} > Neutral </V2Button> <V2Button onClick={() => { setStep2Status('info'); setStep2AriaText('Info'); }} > Info </V2Button> <V2Button onClick={() => { setStep2Status('warning'); setStep2AriaText('Warning'); }} > Warning </V2Button> <V2Button onClick={() => { setStep2Status('error'); setStep2AriaText('Error'); }} > Error </V2Button> </Layout.Group> <V2Timeline activeStep={2}> <V2Timeline.Step title="Lorem ipsum" date={dayjs('2025-05-30').format('MM/DD/YYYY')} /> <V2Timeline.Step title={step2Status.charAt(0).toUpperCase() + step2Status.slice(1)} status={step2Status} ariaText={step2AriaText} date={dayjs('2025-05-31').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Amet consectetur" status="error" date={dayjs('2025-06-01').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Adipiscing elit" status="info" date={dayjs('2025-06-02').format('MM/DD/YYYY')} /> </V2Timeline> </Layout.Stack> ); }; ``` ### Description Use the `description` prop to add a short description for the step. More information can be provided in the [detail card](#card-config) when using the `'card'` type Timeline. ```jsx live () => { return ( <V2Timeline activeStep={1}> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-05-30').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Dolor sit" date={dayjs('2025-05-31').format('MM/DD/YYYY')} description="Lorem ipsum dolor sit amet consectetur adipiscing." /> </V2Timeline> ); }; ``` ### Button Use the `button` prop to add a button to the step. The `button` prop accepts an object of type `V2ButtonProps`, which accepts most props of the [V2Button](/web/ui/button-v2) component, with the exception of `size` and `variant`, which are set by the Timeline and cannot be altered. ```jsx live () => { return ( <V2Timeline activeStep={1}> <V2Timeline.Step title="Lorem ipsum" date={dayjs('2025-05-30').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Dolor sit" date={dayjs('2025-05-31').format('MM/DD/YYYY')} button={{ children: 'Action', onClick: () => { console.log('Action clicked'); }, }} /> </V2Timeline> ); }; ``` ### Helper Use the `helper` prop to display an info icon next to the title. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip-v2) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip-v2) or a [Popover](/web/ui/popover-v2). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip-v2/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live () => { const PopoverTrigger = styled(IconSymbol, { color: '$timeline-v2.color.icon.info-icon.rest', '&:hover': { color: '$timeline-v2.color.icon.info-icon.hover !important', }, '&:active': { color: '$timeline-v2.color.icon.info-icon.active !important', }, }); return ( <V2Timeline activeStep={1}> <V2Timeline.Step title="Tooltip helper" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-05-30').format('MM/DD/YYYY')} helper="Duis aute irure dolor in reprehenderit in voluptate." /> <V2Timeline.Step title="Custom popover helper" date={dayjs('2025-05-31').format('MM/DD/YYYY')} description="Lorem ipsum dolor sit amet consectetur adipiscing." helper={ <V2Popover title="Custom Helper" content="Duis aute irure dolor in reprehenderit in voluptate." > <PopoverTrigger icon="info" variant="outlined" color="$timeline-v2.color.icon.info-icon.rest" size="$timeline-v2.sizing.icon.all.step.info-icon" isScreenReadable title="Info" /> </V2Popover> } /> </V2Timeline> ); }; ``` ## Title Use the `title` prop to set the title of the Timeline. The default is `"Timeline history"`. By default, the title is rendered as an `<h3>`, but this can be configured using the `headingLevel` prop. ```jsx live () => { return ( <V2Timeline title="Custom title" headingLevel={4} activeStep={3}> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-05-30').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-05-31').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-06-01').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-06-02').format('MM/DD/YYYY')} /> </V2Timeline> ); }; ``` ## Active step Use the `activeStep` prop to set the currently active step in the Timeline. This prop accepts the 1-indexed step number (i.e. `1` is the first step, not `0`). Note: If the value of `activeStep` is higher than the number of steps, the Timeline will display all steps as complete without any using the active step styling. ```jsx live () => { return ( <V2Timeline title="Timeline history" activeStep={3}> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-05-30').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-05-31').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-06-01').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-06-02').format('MM/DD/YYYY')} /> </V2Timeline> ); }; ``` ## Active step completion state By default, the `activeStep` will be in progress. Use the `activeStepCompletionState` prop to change the completion state of the active step. The available states are `'in-progress'` and `'completed'`. The default value it `'in-progress'`. Note: Use `'completed'` to indicate that the current step in the process is complete, but the next step hasn't yet begun ```jsx live () => { return ( <V2Timeline title="Timeline history" activeStep={3} activeStepCompletionState="completed" > <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-05-30').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-05-31').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-06-01').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-06-02').format('MM/DD/YYYY')} /> </V2Timeline> ); }; ``` ## Type Use the `type` prop to change the appearance of the Timeline. The `'card'` type displays the Timeline in a card and includes a detail card to display more information about the current step. The `'simple'` type displays the Timeline without any container or detail card. The default value is `'card'`. ```jsx live () => { return ( <V2Timeline type="card" activeStep={2}> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-05-30').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-05-31').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-06-01').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-06-02').format('MM/DD/YYYY')} /> </V2Timeline> ); }; ``` ```jsx live () => { return ( <V2Timeline type="simple" activeStep={2}> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-05-30').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-05-31').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-06-01').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-06-02').format('MM/DD/YYYY')} /> </V2Timeline> ); }; ``` ## Extra content Use the `extraContent` prop to add custom content below the Timeline. ```jsx live () => { return ( <V2Timeline type="card" activeStep={2} extraContent={ <V2Link href="#extra-content" afterIcon="chevron_right"> Lorem ipsum </V2Link> } > <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-05-30').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-05-31').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-06-01').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-06-02').format('MM/DD/YYYY')} /> </V2Timeline> ); }; ``` ## Card config The `cardConfig` prop allows you to customize the detail card for the `'card'` type Timeline. It accepts an object of the following type: ```ts { ariaText?: string; headingLevel?: 1 | 2 | 3 | 4 | 5 | 6; helper?: ReactNode | string; description?: string; extraContent?: ReactNode; buttons?: { filledButton: V2ButtonProps; outlineButton?: V2ButtonProps; }; } ``` The `ariaText` prop adds additional text for screen readers to be read before the card title. The `headingLevel` prop sets the heading level of the card title, which is an `<h2>` by default. The `helper` prop displays an info icon next to the title. See [Helper](#helper) above for more information on how to use it. The `description` prop adds a longer description of the current step. The `extraContent` prop allows you to add additional JSX content to the detail card. The `buttons` prop allows you to add buttons to the detail card. `V2ButtonProps` is an object that accepts most props of the [V2Button](/web/ui/button-v2) component, with the exception of `size` and `variant`, which are set by the Timeline and cannot be altered. When using `buttons`, the `filledButton` is always required, but the `outlineButton` is optional. ```jsx live () => { return ( <V2Timeline activeStep={1} cardConfig={{ ariaText: 'Warning', headingLevel: 3, helper: 'Duis aute irure dolor in reprehenderit in voluptate.', description: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.', extraContent: ( <V2Link href="#card-config" afterIcon="chevron_right"> Learn more </V2Link> ), buttons: { filledButton: { children: 'Filled', onClick: () => { console.log('Filled action clicked'); }, }, outlineButton: { children: 'Outline', onClick: () => { console.log('Outline action clicked'); }, }, }, }} > <V2Timeline.Step title="Lorem ipsum" date={dayjs('2025-05-30').format('MM/DD/YYYY')} status="error" /> <V2Timeline.Step title="Dolor sit" date={dayjs('2025-05-31').format('MM/DD/YYYY')} /> </V2Timeline> ); }; ``` ## Comparison to StepTracker Timeline and [StepTracker](/web/ui/step-tracker-v2) are similar components, but should not be used interchangeably. Both components display a history of completed steps in, the current progress of, and information about the remaining steps in a process. What differentiates one from the other is whether the information displayed is based on immediate user engagement with the user interface or not. ### Timeline The Timeline component is used to inform users of the status of a process with no immediate user input. An example is a claims submission status page where the user can see the progress of their claim through the various stages, but cannot interact with the steps directly. ```jsx live () => { return ( <V2Timeline activeStep={3}> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-05-30').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-05-31').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-06-01').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Lorem ipsum" description="Lorem ipsum dolor sit amet consectetur adipiscing." date={dayjs('2025-06-02').format('MM/DD/YYYY')} /> </V2Timeline> ); }; ``` ### StepTracker The StepTracker is used to guide people through a number of steps to complete in a process. The user navigates through the steps with other components in the UI, typically buttons. An example is a multi-step form where the user fills out information in each step and can navigate back and forth between steps. ```jsx live () => { const paginationProps = usePagination({ pages: 6 }); const steps = [ 'Personal Information', 'Qualifications', 'Practice Information', 'Locations', 'Review & Confirm', ]; return ( <React.Fragment> <V2StepTracker steps={steps} currentStep={paginationProps.state.currentPage} /> <Layout.Group style={{ marginTop: 10 }}> <V2Button onClick={paginationProps.previousPage} variant="outline" isDisabled={!paginationProps.canPreviousPage} > Previous </V2Button> <V2Button onClick={paginationProps.nextPage} isDisabled={!paginationProps.canNextPage} > Next </V2Button> </Layout.Group> </React.Fragment> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2Timeline" propTypeName="TimelineProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2WebPropsTable title="V2Timeline.Step" propTypeName="TimelineStepProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2ClassesTable title="V2Timeline" classes={[TimelineClassesMetadata]} /> ``` ```jsx render <Docs.V2ClassesTable title="V2Timeline.Step" classes={[TimelineStepClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> ```jsx live () => { return ( <V2Timeline activeStep={3} title="Order history" headingLevel={2} cardConfig={{ headingLevel: 1, helper: 'Review the options below to change your order', ariaText: 'Issue,', description: 'One or more items in your order is out of stock. You can request a partial shipment now of the items we have in stock. We will ship the rest when we have them. Otherwise, we will ship it when we have everything. Alternatively, you can cancel your entire order.', extraContent: ( <V2Link href="#" afterIcon="chevron_right"> Learn more </V2Link> ), buttons: { filledButton: { children: 'Ship partial order', onClick: () => { console.log('Filled action clicked'); }, }, outlineButton: { children: 'Cancel order', onClick: () => { console.log('Outline action clicked'); }, }, }, }} > <V2Timeline.Step title="Order" description="We received your order" date={dayjs('2025-05-30').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Payment" description="We received your payment" date={dayjs('2025-05-31').format('MM/DD/YYYY')} /> <V2Timeline.Step title="Processing (delayed)" helper="See details above for more options" status="warning" ariaText="Issue," description="We're preparing your order, but there are delays." date={dayjs('2025-05-31').format('MM/DD/YYYY')} button={{ children: 'Ship partial order', onClick: () => { console.log('Action clicked'); }, }} /> <V2Timeline.Step title="Shipped" /> <V2Timeline.Step title="Delivered" /> </V2Timeline> ); }; ``` </Tab> <Tab label="Tokens"> <h2>Component Tokens</h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={V2Timeline} keys={['timelineV2']} /> ``` </Tab> --- id: timeline category: Content title: Timeline description: Display a list of content in chronological order. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=30822-115373 subDirectory: Timeline/v1 --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="Timeline"></Docs.V2MigrationBanner> ``` ```jsx import { Timeline } from '@uhg-abyss/web/ui/Timeline'; ``` ```jsx sandbox { component: 'Timeline', inputs: [ { prop: 'align', type: 'select', options: [ { label: 'left', value: 'left' }, { label: 'right', value: 'right' }, ], }, { prop: 'active', type: 'string', defaultValue: 1, }, { prop: 'color', type: 'string', }, { prop: 'lineWidth', type: 'string' }, { prop: 'horizontal', type: 'boolean' }, { prop: 'centeredItems', type: 'boolean', }, { prop: 'title', type: 'string', }, ], } () => { return ( <Timeline > <Timeline.Item title="Section 1"> <Text size="sm">Section 1 text</Text> </Timeline.Item> <Timeline.Item title="Section 2"> <Text size="sm">Section 2 text</Text> </Timeline.Item> <Timeline.Item title="Section 3"> <Text size="sm">Section 3 text</Text> </Timeline.Item> <Timeline.Item title="Section 4"> <Text size="sm">Section 4 text</Text> </Timeline.Item> </Timeline> ); }; ``` ## Align Use `align` to set `left` or `right` alignment on a vertical timeline. ```jsx live () => { return ( <Timeline align={'right'}> <Timeline.Item title="Section 1"> <Text size="sm">Section 1 text</Text> </Timeline.Item> <Timeline.Item title="Section 2"> <Text size="sm">Section 2 text</Text> </Timeline.Item> <Timeline.Item title="Section 3"> <Text size="sm">Section 3 text</Text> </Timeline.Item> <Timeline.Item title="Section 4"> <Text size="sm">Section 4 text</Text> </Timeline.Item> </Timeline> ); }; ``` ## Horizontal and centered items Set `horizontal` to `true` for a horizontal timeline. Use `centeredItems` to center bullets and content. ```jsx live () => { return ( <Timeline horizontal> <Timeline.Item title="Section 1"> <Text size="sm">Section 1 text</Text> </Timeline.Item> <Timeline.Item title="Section 2"> <Text size="sm">Section 2 text</Text> </Timeline.Item> <Timeline.Item title="Section 3"> <Text size="sm">Section 3 text</Text> </Timeline.Item> <Timeline.Item title="Section 4"> <Text size="sm">Section 4 text</Text> </Timeline.Item> </Timeline> ); }; ``` ```jsx live () => { return ( <Timeline horizontal centeredItems={true}> <Timeline.Item title="Section 1"> <Text size="sm">Section 1 text</Text> </Timeline.Item> <Timeline.Item title="Section 2"> <Text size="sm">Section 2 text</Text> </Timeline.Item> <Timeline.Item title="Section 3"> <Text size="sm">Section 3 text</Text> </Timeline.Item> <Timeline.Item title="Section 4"> <Text size="sm">Section 4 text</Text> </Timeline.Item> </Timeline> ); }; ``` ## Color and active Use `color` and `active` to show timeline progression. `active` must match or exceed the index of the item you wish to color. ```jsx live () => { return ( <Timeline color={'$interactive1'} active={2}> <Timeline.Item title="Section 1"> <Text size="sm">Section 1 text</Text> </Timeline.Item> <Timeline.Item title="Section 2"> <Text size="sm">Section 2 text</Text> </Timeline.Item> <Timeline.Item title="Section 3"> <Text size="sm">Section 3 text</Text> </Timeline.Item> <Timeline.Item title="Section 4"> <Text size="sm">Section 4 text</Text> </Timeline.Item> </Timeline> ); }; ``` ```jsx live () => { return ( <Timeline color={'$interactive1'} horizontal active={2} centeredItems={true} > <Timeline.Item title="Section 1"> <Text size="sm">Section 1 text</Text> </Timeline.Item> <Timeline.Item title="Section 2"> <Text size="sm">Section 2 text</Text> </Timeline.Item> <Timeline.Item title="Section 3"> <Text size="sm">Section 3 text</Text> </Timeline.Item> <Timeline.Item title="Section 4"> <Text size="sm">Section 4 text</Text> </Timeline.Item> </Timeline> ); }; ``` ## Line width Use `lineWidth` to set the thickness of the center line. ```jsx live () => { return ( <Timeline lineWidth={4}> <Timeline.Item title="Section 1"> <Text size="sm">Section 1 text</Text> </Timeline.Item> <Timeline.Item title="Section 2"> <Text size="sm">Section 2 text</Text> </Timeline.Item> <Timeline.Item title="Section 3"> <Text size="sm">Section 3 text</Text> </Timeline.Item> <Timeline.Item title="Section 4"> <Text size="sm">Section 4 text</Text> </Timeline.Item> </Timeline> ); }; ``` ## Timeline.Item Set custom bullets by passing an `IconSymbol` component through the `bullet` prop. ```jsx live () => { return ( <Timeline centeredItems horizontal> <Timeline.Item title="Icon"> <Text size="sm">Default bullet without anything</Text> </Timeline.Item> <Timeline.Item title="Small Icon" bulletSize={12} bullet={ <IconSymbol icon="star" size={'12px'} color={'$gray6'} title="Small Icon" isScreenReadable /> } > <Text size="sm">Timeline bullet with small icon</Text> </Timeline.Item> <Timeline.Item title="Large Icon" bulletSize={35} bullet={ <IconSymbol icon="health_and_safety" size={'35px'} variant="filled" title="Large Icon" isScreenReadable /> } > <Text size="sm">Timeline bullet with large icon</Text> </Timeline.Item> </Timeline> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={Timeline} rows={[ { name: 'align', type: "'left' | 'right'", description: 'sets orientation of vertical timeline', }, { name: 'active', type: 'number', description: 'shows timeline progress by filling color to given index', }, { name: 'color', type: 'string', description: 'colors each section of timeline according to active index', }, { name: 'lineWidth', type: 'number', description: 'Changes width of center line', }, { name: 'horizontal', type: 'boolean', description: 'Changes timeline from vertical to horizontal', }, { name: 'centeredItems', type: 'boolean', description: 'Centers content of horizontal timeline', }, { name: 'title', type: 'string', description: 'title for timeline aria-label', }, ]} /> ``` ```jsx render <Docs.PropsTable of={Timeline.Item} rows={[ { name: 'bullet', type: 'node', description: 'Change default bullet', }, { name: 'title', type: 'string', description: 'Title of the timeline item', }, { name: 'lineVariant', type: "'solid' | 'dashed' | 'dotted'", description: 'Styled of border', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Timeline} rows={[ { name: 'timeline-root', description: 'Root element', }, { name: 'timeline-container', description: 'Container element', }, { name: 'timeline-item', description: 'Item element', }, { name: 'timeline-item-[index]', description: 'Item element with index', }, { name: 'timeline-item-bullet', description: 'Bullet element', }, { name: 'timeline-item-bullet-[index]', description: 'Bullet element with index', }, { name: 'timeline-item-title', description: 'Title element', }, { name: 'timeline-item-title-[index]', description: 'Title element with index', }, { name: 'timeline-item-content', description: 'Content element', }, { name: 'timeline-item-content-[index]', description: 'Content element with index', }, ]} /> ``` </Tab> <Tab label="Accessibility"> <h2>Differences with StepIndicator</h2> The Timeline and [StepIndicator](/web/ui/step-indicator) components are similar in appearance and function but have different intended uses. Timeline is used to display progress through static content. StepIndicator is used to indicate progress through a process involving user input. ```jsx live () => { return ( <Timeline color={'$interactive1'} active={2}> <Timeline.Item title="Menu"> <Text size="sm">Review our options</Text> </Timeline.Item> <Timeline.Item title="Order"> <Text size="sm">Make your selections</Text> </Timeline.Item> <Timeline.Item title="Review"> <Text size="sm">Confirm order and destination</Text> </Timeline.Item> <Timeline.Item title="Payment"> <Text size="sm">Last step before purchase</Text> </Timeline.Item> <Timeline.Item title="Prepare order"> <Text size="sm">We cook your food</Text> </Timeline.Item> <Timeline.Item title="Delivery"> <Text size="sm">Our drivers come to you</Text> </Timeline.Item> <Timeline.Item title="Receive order"> <Text size="sm">Your meal arrives</Text> </Timeline.Item> <Timeline.Item title="Eat meal"> <Text size="sm">Enjoy your order</Text> </Timeline.Item> <Timeline.Item title="Rate order"> <Text size="sm">Tell us how we did</Text> </Timeline.Item> </Timeline> ); }; ``` ```jsx live () => { const paginationProps = usePagination({ pages: 9 }); const buttonMessage = paginationProps.state.currentPage >= paginationProps.state.pageCount - 1 ? 'Submit' : 'Next'; return ( <React.Fragment> <Box width="50%"> <StepIndicator horizontalScroll currentStep={paginationProps.state.currentPage} > <StepIndicator.Step label="Menu" icon={<IconSymbol icon="local_pizza" />} /> <StepIndicator.Step label="Order" icon={<IconSymbol icon="add_shopping_cart" />} /> <StepIndicator.Step label="Review" icon={<IconSymbol icon="done_outline" />} /> <StepIndicator.Step label="Payment" icon={<IconSymbol icon="credit_card" />} /> <StepIndicator.Step label="Prepare Order" icon={<IconSymbol icon="hourglass_empty" />} /> <StepIndicator.Step label="Deliver" icon={<IconSymbol icon="local_shipping" />} /> <StepIndicator.Step label="Receive Order" icon={<IconSymbol icon="home" />} /> <StepIndicator.Step label="Eat Meal" icon={<IconSymbol icon="face" />} /> <StepIndicator.Step label="Rate Order" icon={<IconSymbol icon="thumbs_up_down" />} /> </StepIndicator> </Box> <Layout.Group style={{ marginTop: 10 }}> <Button data-id="1" onClick={paginationProps.previousPage} variant="outline" isDisabled={!paginationProps.canPreviousPage} > Previous </Button> <Button data-id="2" onClick={paginationProps.nextPage} isDisabled={!paginationProps.canNextPage} > {buttonMessage} </Button> </Layout.Group> </React.Fragment> ); }; ``` </Tab> --- id: toast-v2 category: Feedback title: V2Toast description: Notifications system design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=24-10269&p=f&m=dev subDirectory: Toast/v2/Toast sourceIsTS: true --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="Toast"></Docs.V2MigrationBanner> ``` ```jsx import { V2ToastProvider } from '@uhg-abyss/web/ui/Toast'; ``` ## Overview V2Toast is a notification system designed to provide feedback to users in a non-intrusive way. To use the V2Toast component, you need to wrap your application with the `V2ToastProvider` component. This provider manages the state and rendering of toasts. It is recommended to place it inside the `ThemeProvider` to ensure consistent styling across your application. ```jsx import { ThemeProvider } from '@uhg-abyss/web/ui/ThemeProvider'; import { V2ToastProvider } from '@uhg-abyss/web/ui/Toast'; function Demo() { return ( <ThemeProvider> <V2ToastProvider /> <App /> </ThemeProvider> ); } ``` ## Methods All methods can be accessed via the `useToastV2` hook and can be used in any part of your application: ```jsx import { useToastV2 } from '@uhg-abyss/web/hooks/useToastV2'; const { toast } = useToastV2(); ``` - `toast.show` - adds given toast to toasts list or queue depending on current state. Message is required. - `toast.update` - updates toast that was previously added to the state or queue. Message is required. - `toast.hide` - removes toast with given id from toasts state and queue. Id is required. - `toast.clean` - removes all toasts from toasts state and queue - `toast.cleanQueue` - removes all toasts from queue ## Toast props Each toast state item can have these properties: - `id` - toast ID, used to update and remove a toast. By default, this ID is randomly generated - `title` - toast title, displayed above the message - `message` - required toast body - `type` - style of toast and icons: `'info'`, `'success'`, `'warning'` and `'error'` - `withCloseButton` - determines whether close button should be visible - `background` - background style of toast: `'saturated'` or `'tint'` - `onClose` - calls when toast is unmounted - `autoClose` - defines a timeout in ms on which toast will be automatically closed, use `false` to disable auto close - `icon` - override default icon - `hideIcon` - flag to hide the left icon - `onOpen` - calls when toast is mounted - `button` - an object where a custom CTA can be passed in (see [Button example](#button) below) When showing or updating a toast, all properties except `message` are optional. ```jsx import { IconSymbol } from '@uhg-abyss/web/ui/IconSymbol'; import { useToastV2 } from '@uhg-abyss/web/hooks/useToastV2'; const { toast } = useToastV2(); // Bare minimum - message is required for all toasts toast.show({ message: 'Hello' }); // Most used toast props toast.show({ id: 'hello-there', withCloseButton: true, onClose: () => console.log('unmounted'), onOpen: () => console.log('mounted'), autoClose: 5000, title: 'Toast title', message: 'Toast message', type: 'info', background: 'saturated', icon: <IconSymbol icon="home" />, }); ``` ## Usage examples ### Type and background The toast notification supports different visual styles using the `type` prop (default: `'error'`). The available types are: - `'info'`: For informational messages. - `'success'`: Indicates a successful operation. - `'warning'`: Alerts the user about potential issues. - `'error'`: Denotes a problem or critical error. In addition, the `background` prop offers two style options: - `'saturated'`: A bold, vibrant background for higher emphasis. This is the default. - `'tint'`: A softer, lighter background for a subtle appearance. Below is an example demonstrating how to generate toasts with each type and background variation: ```jsx live () => { const { toast } = useToastV2(); const types = ['info', 'success', 'warning', 'error']; const backgrounds = ['saturated', 'tint']; const generateToasts = () => { let delay = 0; types.forEach((type) => { backgrounds.forEach((background) => { setTimeout(() => { toast.show({ title: `${type.toUpperCase()} - ${background.toUpperCase()}`, message: 'This is a toast message', type, background, autoClose: false, withCloseButton: true, }); }, delay); delay += 500; }); }); }; return ( <Layout.Group> <V2Button onClick={generateToasts}>Show all toasts</V2Button> <V2Button onClick={() => toast.clean()}>Clean all</V2Button> </Layout.Group> ); }; ``` ### Closing props You can pass two different props related to closing: - `autoClose`: Accepts either a number or a boolean. If given a number, the toast will automatically close after that many milliseconds. If given `false`, the toast will not auto-close. The default is `5000`. This prop can be passed in with the `show` or `update` methods [explained above](#methods). - `withCloseButton`: By default `true`, allows you to hide/display the close button at the top right of the toast. Note: Avoid setting both `autoClose` and `withCloseButton` to `false`. The fourth example below showcases this scenario that you must avoid. See the [Accessibility tab](/web/ui/toast-v2?tab=accessibility) for more info. ```jsx live () => { const { toast } = useToastV2(); return ( <Layout.Group css={{ flexWrap: 'wrap', '.abyss-button-root': { marginBottom: '$sm', }, }} > <V2Button onClick={() => toast.show({ type: 'info', title: 'Default closing toast', message: 'This toast will auto-close after five seconds and it has a close button.', }) } > Show default </V2Button> <V2Button onClick={() => toast.show({ type: 'info', title: 'Auto closing toast', message: 'This toast will auto-close after nine seconds. It has no close button.', autoClose: 9000, withCloseButton: false, }) } > Show 9-second toast </V2Button> <V2Button onClick={() => toast.show({ type: 'info', title: 'User closing toast', message: 'This toast will not auto-close. Click the button at the top right to close it.', autoClose: false, }) } > Show manually closing toast </V2Button> <V2Button color="destructive" onClick={() => toast.show({ title: 'Wrong prop usage', message: 'This toast will never auto-close and it cannot be closed manually. Avoid doing this! To close it, you must use the "Clean all" button.', autoClose: false, withCloseButton: false, }) } > Show never closing toast </V2Button> <V2Button onClick={() => toast.clean()}>Clean all</V2Button> </Layout.Group> ); }; ``` ### CTA Use the `cta` prop to add a call to action to the Alert. The `cta` prop accepts an object of the following type: ```ts { type: 'button' | 'link', props: V2ButtonProps | V2LinkProps, } ``` `V2ButtonProps` and `V2LinkProps` are objects that accept most props of the [V2Button](/web/ui/button-v2) and [V2Link](/web/ui/link-v2) components, respectively, except for `size`, which is set by the Alert and cannot be altered. ```jsx live () => { const { toast } = useToastV2(); const navigateToSettings = () => { window.location.href = '#'; }; return ( <Layout.Group css={{ flexWrap: 'wrap', '.abyss-button-root': { marginBottom: '$sm', }, }} > <V2Button onClick={() => toast.show({ title: 'Important Notice', message: 'Your preferences have been saved. Click thebutton below to go to the Settings page', cta: { type: 'button', props: { children: 'Button', onClick: () => { console.log('CTA button clicked'); }, }, }, type: 'info', background: 'tint', autoClose: 9000, }) } > Show toast with button </V2Button> <V2Button onClick={() => toast.show({ title: 'Important Notice', message: 'Your preferences have been saved. Click thebutton below to go to the Settings page', cta: { type: 'link', props: { children: 'Link', href: '#cta', onClick: () => { console.log('CTA link clicked'); }, }, }, type: 'info', background: 'tint', autoClose: 9000, }) } > Show toast with link </V2Button> </Layout.Group> ); }; ``` ### Updating existing toast You can update an existing toast by targeting the `id` using the `update` method. ```jsx live () => { const { toast } = useToastV2(); return ( <Layout.Group> <V2Button onClick={() => { toast.show({ id: 'info-data', title: 'Request Received', type: 'info', message: 'Processing your request. This toast will update in 3 seconds.', autoClose: false, }); setTimeout(() => { toast.update({ id: 'info-data', title: 'Your request was successful', type: 'success', message: 'Your request has been successfully processed. Thank you for your patience.', }); }, 3000); }} > Show update toast </V2Button> </Layout.Group> ); }; ``` ## Position `ToastProvider` renders the toasts' container with fixed position inside a React Portal at the bottom right of the screen. On mobile, the toasts will be displayed from the top center. The position cannot be changed. ## State and queue `V2ToastProvider` uses a queue hook to manage state. There is no limit for the toasts in the queue; these will accumulate until they are auto-closed or manually removed. Note: Whenever the amount of toasts reaches the visual height limit of the container, the container becomes scrollable and a "Clear all" button appears at the top right. ```jsx live () => { const { toast } = useToastV2(); const types = ['info', 'success', 'warning', 'error']; return ( <Layout.Group> <V2Button onClick={() => { Array(20) .fill(0) .forEach((_, index) => { const type = types[index % types.length]; setTimeout(() => { toast.show({ title: `${ type.charAt(0).toUpperCase() + type.slice(1) } Toast ${index + 1}`, message: `This is a ${type} message with tint background`, type: type, background: 'tint', autoClose: false, }); }, 200 * index); }); }} > Show 20 toasts </V2Button> <V2Button onClick={() => { toast.clean(); }} > Clean all </V2Button> </Layout.Group> ); }; ``` ## Clear state and queue To remove specific toast from state or queue, use `toast.hide` function: ```jsx toast.show({ id: 'hello', message: 'Hello!' }); toast.hide('hello'); ``` Use the `v2toast.cleanQueue` function to remove all toasts that are not currently displayed, and the `v2toast.clean` function to remove all toasts from state and queue. ```jsx live () => { const { toast } = useToastV2(); return ( <Layout.Group css={{ flexWrap: 'wrap', '.abyss-button-root': { marginBottom: '$sm', }, }} > <V2Button onClick={() => { toast.show({ id: 'alert', title: 'Alert Toast', message: 'There was an error processing your request', autoClose: false, }); }} > Show alert toast </V2Button> <V2Button onClick={() => { toast.hide('alert'); }} > Hide alert toast </V2Button> <V2Button onClick={() => { Array(10) .fill(0) .forEach((_, index) => { toast.show({ title: `Toast ${index + 1}`, message: 'Most toasts are added to queue', }); }); }} > Show 10 toasts </V2Button> <V2Button onClick={() => { toast.cleanQueue(); }} > Clean queue </V2Button> <V2Button onClick={() => { toast.clean(); }} > Clean all </V2Button> </Layout.Group> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2Toast" propTypeName="V2ToastProps" /> ``` ```jsx render <Docs.V2ClassesTable title="V2Toast" classes={[V2ToastClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> Toast elements should never present content that is mandatory reading. Toast messages should always be short and concise. Toasts that close automatically are more accessible than those that require manual interaction. Accessing Toasts by keyboard is difficult. Avoid placing interactive elements within Toasts. To ensure the best user experience, it's strongly recommended to either enable auto-closing (`autoclose` is defined) or provide a close button (`withCloseButton` is set to `true`). Setting both `autoClose` and `withCloseButton` to `false` results in a permanent, non-dismissible Toast, which goes against the concept of a Toast as a temporary, non-modal dialog. Should you choose to keep the Toast open indefinitely and non-dismissible, be mindful of accessibility concerns and ensure there are alternative means to remove the Toast. Toast Utilizes the <ExitLink href="https://www.w3.org/TR/wai-aria-practices-1.2/#alert">WAI-ARIA Log role</ExitLink>. There is no WAI-ARIA standard for toast. Look at the links below for toast accessibility references. It is suggested to include the hidden keyboard shortcut (Accesskey -A) on sticky toasts. - <ExitLink href="https://sheribyrnehaber.medium.com/designing-toast-messages-for-accessibility-fb610ac364be"> Sheri Byrne-Haber: Designing Toast Messages for Accessibility </ExitLink> - <ExitLink href="https://www.scottohara.me/blog/2019/07/08/a-toast-to-a11y-toasts.html"> Scott O'Hara: A toast to an accessible toast... </ExitLink> - <ExitLink href="https://adrianroselli.com/2020/01/defining-toast-messages.html"> Adrian Roselli: Defining ‘Toast’ Messages </ExitLink> <h3> BrAT Accesskey Variations </h3> <h5>Windows</h5> - Chrome: Alt + A - Edge: Alt + A - Firefox: Alt + Shift + A <h5>MacOS</h5> - Safari - Without VoiceOver: Control + Option + A - With VoiceOver: Control + A - Chrome - Without VoiceOver: Control + Option + A - With VoiceOver: Control + Option + Tab (enables pass-through mode) _then_ Control + Option + A For more information about accesskey BrAT implementations see: <ExitLink href="https://pauljadam.com/demos/accesskey.html">Accesskey Accessibility Demo (pauljadam.com)</ExitLink> <h3> Reduced Motion </h3> Animations and transitions that have been changed when a user has `prefers-reduced-motion` set to `reduced`: - Left/right slide transitions for queue display and updates have been removed ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Escape', description: 'Closes the current toast and moves focus accordingly.', }, { name: 'Accesskey -A', description: 'Jump to (last) toast', }, ]} /> ``` ```jsx live () => { const { toast } = useToastV2(); return ( <Layout.Stack alignItems="left"> <h2>Toast examples</h2> <Layout.Group css={{ flexWrap: 'wrap', '.abyss-button-root': { marginBottom: '$sm', }, }} > <V2Button onClick={() => toast.show({ type: 'info', title: 'Default info toast', message: 'By default, toasts have close buttons and clear after 5 seconds.', }) } > Default </V2Button> <V2Button onClick={() => toast.show({ type: 'success', title: 'Configurable display time', message: 'This success toast displays for 10 seconds then clears. This is why it can have no close button', autoClose: 10000, withCloseButton: false, }) } > Configurable display time </V2Button> <V2Button onClick={() => toast.show({ type: 'warning', title: 'Manual-only toast', message: 'This toast does not close automatically. The close button or Escape key are required. Keyboard users must use access key + A to set focus to the toast to do this. This is why it should be avoided.', autoClose: false, }) } > Manual close </V2Button> <V2Button onClick={() => { toast.show({ id: 'info-data', title: 'Simulating transaction', type: 'info', message: 'Processing request. This toast will update in 4 seconds so it has no close button.', autoClose: false, withCloseButton: false, }); setTimeout(() => { toast.update({ id: 'info-data', title: 'Simulation completed', type: 'success', message: 'Request successfully processed. This toast has a close button and clears after 4 seconds.', }); }, 4000); }} > Automatic updates </V2Button> <V2Button onClick={() => { Array(10) .fill(0) .forEach((_, index) => { setTimeout(() => { toast.show({ type: 'info', title: `Toast ${index + 1}`, message: `This message closes in ${ 2 * (index + 1) } seconds.`, autoClose: 2000 * (index + 1), }); }, 100 * index); }); }} > 10 automatic toasts </V2Button> <V2Button color="destructive" onClick={() => toast.show({ title: 'Bad toast', message: 'This toast will never auto-close and it cannot be closed manually. Avoid doing this! To close it, you must use the "Close all toasts" button.', autoClose: false, withCloseButton: false, }) } > Bad example </V2Button> <V2Button onClick={() => toast.clean()}>Close all toasts</V2Button> </Layout.Group> </Layout.Stack> ); }; ``` </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={'V2Toast'} keys={['toastV2']} /> ``` </Tab> --- id: toast category: Feedback title: Toast description: Notifications system design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=39848-121318 subDirectory: Toast/v1/Toast --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="Toast"></Docs.V2MigrationBanner> ``` ```jsx import { ToastProvider } from '@uhg-abyss/web/ui/Toast'; ``` ## Usage Add the ToastProvider component anywhere in your application, usually it is placed inside ThemeProvider next to your App component: ```jsx import { ThemeProvider } from '@uhg-abyss/web/ui/ThemeProvider'; import { ToastProvider } from '@uhg-abyss/web/ui/Toast'; function Demo() { return ( <ThemeProvider> <ToastProvider /> <App /> </ThemeProvider> ); } ``` ## Examples ```jsx live () => { const { toast } = useToast(); return ( <Layout.Group css={{ flexWrap: 'wrap', '.abyss-button-root': { marginBottom: '$sm', }, }} > <Button onClick={() => toast.show({ title: 'Default toast title', message: 'Default toast message', }) } > Default </Button> <Button onClick={() => toast.show({ title: 'Loading...', message: 'Loading example', isLoading: true, ariaLoadingLabel: 'Loading example', variant: 'info', }) } > Loading </Button> <Button onClick={() => toast.show({ title: 'Success variant toast', message: 'Default toast message', variant: 'success', }) } > Success Variant </Button> <Button onClick={() => toast.show({ title: 'Custom autoClose timeout', message: 'Toast will be closed in 10 seconds', autoClose: 10000, }) } > 10 second timeout </Button> <Button onClick={() => toast.show({ title: 'Will never close', message: 'This Toast will remain open', autoClose: false, }) } > Never closes </Button> <Button onClick={() => toast.show({ title: 'Custom', message: ( <Layout.Stack alignItems="left"> <Text color="$white">Custom Message Node</Text> <Link color="$white" colorHover="$interactive3" fontWeight="$bold" href="#" > Action </Link> </Layout.Stack> ), variant: 'info', }) } > Custom Node </Button> </Layout.Group> ); }; ``` ## Methods All methods can be used from `@uhg-abyss/web/hooks/useToast` hook and can be used in any part of your application: ```jsx import { useToast } from '@uhg-abyss/web/hooks/useToast'; const { toast } = useToast(); ``` - toast.show – adds given toast to toasts list or queue depending on current state and limit. Message is required. - toast.update – updates toast that was previously added to the state or queue. Message is required. - toast.hide – removes toast with given id from toasts state and queue. Id is required. - toast.clean – removes all toasts from toasts state and queue - toast.cleanQueue – removes all toasts from queue ## Toast props Toast state item can have these properties: - id – toast id, which is used to update and remove a toast. By default, id is randomly generated - withCloseButton – determines whether close button should be visible - onClose – calls when toast is unmounted - onOpen – calls when toast is mounted - autoClose – defines timeout in ms on which toast will be automatically closed, use `false` to disable auto close - message – required toast body - isLoading – flag to show loading spinner - hideIcon - flag to hide icon - icon – override default icon - variant - style of toast and icons: `'error'`, `'info'`, `'success'`, and `'warning'` - ariaLoadingLabel - Text to describe what is happening while the loading spinner is active inside the Toast component. Do not duplicate visible text. Only use to supplement the text that follows graphic When showing or updating a toast, all properties except message are optional. Note: Avoid setting both autoClose and withCloseButton to false. See the [Accessibility tab](/web/ui/toast?tab=accessibility) for more info. ```jsx import { IconSymbol } from '@uhg-abyss/web/ui/IconSymbol'; import { useToast } from '@uhg-abyss/web/hooks/useToast'; const { toast } = useToast(); // Bare minimum – message is required for all toasts toast.show({ message: 'Hello' }); // Most used toast props toast.show({ id: 'hello-there', withCloseButton: true, onClose: () => console.log('unmounted'), onOpen: () => console.log('mounted'), autoClose: 5000, title: 'Toast title', message: 'Toast message', icon: <IconSymbol icon="home" />, css: { 'abyss-toast-container': { backgroundColor: 'blue' } }, isLoading: true, // ariaLoadingLabel is required when using isLoading ariaLoadingLabel: 'uploading file', }); ``` ## Position `ToastProvider` renders toasts container with fixed position inside a React Portal. Position cannot be changed per toast. `ToastProvider` supports the following positions: - `top-left` - `top-right` - `top-center` - `bottom-left` - `bottom-right` - `bottom-center` ```jsx import { ToastProvider } from '@uhg-abyss/web/ui/Toast'; function Demo() { return <ToastProvider position="top-right" />; } ``` ## Toast limit `ToastProvider` uses a queue hook to manage state. You can limit the maximum amount of toasts that can be displayed by setting the `limit` prop on `ToastProvider`: ```jsx const Demo = () => { return <ToastProvider limit={5} />; }; ``` All toasts added after limit was reached will be added into queue and displayed when toast from current state is closed. ```jsx live () => { const { toast } = useToast(); return ( <Layout.Group> <Button onClick={() => { Array(10) .fill(0) .forEach((_, index) => { setTimeout(() => { toast.show({ title: `Toast ${index + 1}`, message: 'Most toasts are added to queue', }); }, 200 * index); }); }} > Show 10 toasts </Button> </Layout.Group> ); }; ``` ## Clear state and queue To remove specific toast from state or queue, use `toast.hide` function: ```jsx toast.show({ id: 'hello', message: 'Hello!' }); toast.hide('hello'); ``` Use `toast.cleanQueue()` function to remove all toasts that are not currently displayed, and `toast.clean()` function to remove all toasts from state and queue. ```jsx live () => { const { toast } = useToast(); return ( <Layout.Group> <Button onClick={() => { Array(10) .fill(0) .forEach((_, index) => { toast.show({ title: `Toast ${index + 1}`, message: 'Most toasts are added to queue', }); }); }} > Show 10 toasts </Button> <Button onClick={() => { toast.cleanQueue(); }} > Clean queue </Button> <Button onClick={() => { toast.clean(); }} > Clean all </Button> </Layout.Group> ); }; ``` ## Update existing toast You can update an existing toast by targeting the `id` using the update method. ```jsx live () => { const { toast } = useToast(); return ( <Layout.Group> <Button onClick={() => { toast.show({ id: 'load-data', isLoading: true, ariaLoadingLabel: 'loading table data', title: 'Loading your data', variant: 'info', message: 'Data will be loaded in 3 seconds, you cannot close this yet', autoClose: false, withCloseButton: false, }); setTimeout(() => { toast.update({ id: 'load-data', title: 'Data was loaded', variant: 'success', message: 'Toast will close in 2 seconds, you can close this toast now', autoClose: 2000, }); }, 3000); }} > Show update toast </Button> </Layout.Group> ); }; ``` ## Auto close You can configure auto close timeout with `ToastProvider`: ```jsx // All toasts will be closed automatically in 4000ms function Demo() { return <ToastProvider autoClose={4000} />; } ``` Or in `toast.show`/`toast.update` functions: ```jsx toast.show({ message: 'I will close in 500ms seconds', autoClose: 500, }); toast.update({ id: 'hello', message: 'I will never close', autoClose: false, }); ``` `toast.show` and `toast.update` functions `autoClose` prop always has higher priority. </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={ToastProvider} rows={[ { name: 'position', type: 'string', description: "Position where toasts will appear. Options 'top-left', 'top-right', 'top-center' 'bottom-left', 'bottom-right', 'bottom-center'", }, { name: 'autoClose', type: 'boolean | number', description: 'Pass false to turn auto close off. Pass a number in milliseconds to set the time it takes the toast to close', }, { name: 'transitionDuration', type: 'number', description: 'Time it takes in milliseconds for the toast to complete its animation', }, { name: 'containerWidth', type: 'string | number', description: 'Set the width of the container', }, { name: 'toastHeight', type: 'string | number', description: 'Set the height of the the toast', }, { name: 'limit', type: 'number', description: 'The number of toasts that can appear on screen at one time', }, { name: 'zIndex', type: 'number', description: 'Z-index of the toasts', }, { name: 'target', type: 'shape', description: 'The ref where the toasts are portaled', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Toast} rows={[ { name: 'toast-container', description: 'Toast root element', }, { name: 'toast-icon-container', description: 'Toast icon container', }, { name: 'toast-icon', description: 'Toast icon', }, { name: 'toast-loading-container', description: 'Toast loading spinner container', }, { name: 'toast-loading-spinner', description: 'Toast loading spinner', }, { name: 'toast-body', description: 'Toast body', }, { name: 'toast-title', description: 'Toast title', }, { name: 'toast-description', description: 'Toast description', }, { name: 'toast-close-button', description: 'Toast close button', }, { name: 'toast-close-button-icon', description: 'Toast close button icon', }, ]} /> ``` </Tab> <Tab label="Accessibility"> Toasts elements should never present content that is mandatory reading. Toast messages should always be short and concise. Toasts that close automatically are more accessible than those that require manual interaction. Accessing Toasts by keyboard is difficult. Avoid placing interactive elements within Toasts. To ensure the best user experience, it's strongly recommended to either enable auto-closing (`autoclose` is defined) or provide a close button (`withCloseButton` is set to `true`). Setting both `autoClose` and `withCloseButton` to `false` results in a permanent, non-dismissible Toast, which goes against the concept of a Toast as a temporary, non-modal dialog. Should you choose to keep the Toast open indefinitely and non-dismissible, be mindful of accessibility concerns and ensure there are alternative means to remove the Toast. Toast Utilizes the <ExitLink href="https://www.w3.org/TR/wai-aria-practices-1.2/#alert">WAI-ARIA Log role</ExitLink>. There is no WAI-ARIA standard for toast. Look at the links below for toast accessibility references. It is suggested to include the hidden keyboard shortcut (Accesskey -T) on sticky toasts. - <ExitLink href="https://sheribyrnehaber.medium.com/designing-toast-messages-for-accessibility-fb610ac364be"> Sheri Byrne-Haber: Designing Toast Messages for Accessibility </ExitLink> - <ExitLink href="https://www.scottohara.me/blog/2019/07/08/a-toast-to-a11y-toasts.html"> Scott O'Hara: A toast to an accessible toast... </ExitLink> - <ExitLink href="https://adrianroselli.com/2020/01/defining-toast-messages.html"> Adrian Roselli: Defining ‘Toast’ Messages </ExitLink> <h3> BrAT Accesskey Variations </h3> <h5>Windows</h5> - Chrome: Alt + T - Edge: Alt + T - Firefox: Alt + Shift + T <h5>MacOS</h5> - Safari - Without VoiceOver: Control + Option + T - With VoiceOver: Control + T - Chrome - Without VoiceOver: Control + Option + T - With VoiceOver: Control + Option + Tab (enables pass-through mode) _then_ Control + Option + T For more information about accesskey BrAT implementations see: <ExitLink href="https://pauljadam.com/demos/accesskey.html">Accesskey Accessibility Demo (pauljadam.com)</ExitLink> <h3> Reduced Motion </h3> Animations and transitions that have been changed when a user has `prefers-reduced-motion` set to `reduced`: - Left/right slide transitions for queue display and updates have been removed ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Escape', description: 'Closes the current toast and moves focus accordingly.', }, { name: 'Accesskey -T', description: 'Jump to (last) toast', }, ]} /> ``` </Tab> --- id: toggle-v2 category: Forms title: V2Toggle description: Used to switch between on and off between 2 modes. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=10564-18693 subDirectory: Toggle sourceIsTS: true --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="ToggleSwitch"></Docs.V2MigrationBanner> ``` ```jsx import { V2Toggle } from '@uhg-abyss/web/ui/Toggle'; ``` ```jsx sandbox { component: 'V2Toggle', inputs: [ { prop: 'isDisabled', type: 'boolean' }, { prop: 'showIcons', type: 'boolean', defaultValue: true }, { prop: 'label', type: 'string', defaultValue: 'Toggle' }, ] } () => { const [isChecked, setChecked] = useState(true); return ( <V2Toggle isChecked={isChecked} onChange={e => setChecked(e.target.checked)} /> ); }; ``` ## useForm (recommended) Using the `useForm` hook lets the DOM handle form data. Note: The default error message when `required` is `true` is minimally acceptable for accessibility. It is highly recommended to customize it to be more specific to the use of the field and form. ```jsx live () => { const form = useFormV2({ defaultValues: { 'accept-terms': false, }, }); const onSubmit = (data) => { console.log('submitted', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2Toggle model="accept-terms" label="Accept Terms" validators={{ required: true }} /> <V2Button type="submit" size="$sm" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [isChecked, setChecked] = useState(false); return ( <V2Toggle isChecked={isChecked} onChange={(e) => setChecked(e.target.checked)} label="Accept Terms" /> ); }; ``` ## Disabled Use the `isDisabled` property to disable the `Toggle`. The default is set to `false`. ```jsx live () => { const form = useFormV2(); const onSubmit = (data) => { console.log('submitted', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2Toggle isDisabled model="accept-terms" label="Accept Terms" /> </V2FormProvider> ); }; ``` ## Label The `label` prop is required. The prop accepts either a string or an object of the form: ```ts { text: string; position: 'left' | 'right'; } ``` The `position` property determines where the label will be displayed in relation to the toggle. The default value is `'right'`. ```jsx live () => { const form = useFormV2(); const onSubmit = (data) => { console.log('submitted', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2Toggle model="accept-terms" label={{ text: 'Accept Terms', position: 'left' }} /> </V2FormProvider> ); }; ``` ## Subtext Use the `subText` prop to display helpful information related to the input field. The prop accepts either a string or an object of the form: ```ts { text: string; position: 'above' | 'below'; } ``` The `position` property determines where the subtext will be displayed in relation to the input field. The default value is `'below'`. ```jsx live () => { const FormSpacing = React.useMemo( () => styled('div', { display: 'flex', flexDirection: 'column', gap: '$web.semantic.spacing.scale.sm', }), [] ); const form = useFormV2(); const onSubmit = (data) => { console.log('submitted', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <FormSpacing> <V2Toggle model="accept-terms" label="Accept Terms" subText="Subtext with a regular string" /> <V2Toggle model="accept-conditions" label="Accept Conditions" subText={{ text: 'Subtext passed above the input', position: 'above', }} /> <V2Toggle model="accept-contract" label="Accept Contract" subText={{ text: 'Subtext passed below the input', position: 'below', }} /> </FormSpacing> </V2FormProvider> ); }; ``` ## Error message (useState) ```jsx render <Docs.FormCompatibilityWidget useState /> ``` Use the `errorMessage` prop to display a custom error message below the input field when using `useState`. ```jsx live () => { const [isChecked, setChecked] = useState(false); return ( <V2Toggle isChecked={isChecked} onChange={(e) => setChecked(e.target.checked)} label="Accept Terms" errorMessage="Custom error message" /> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2Toggle" propTypeName="ToggleProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2ClassesTable title="V2Toggle" classes={[ToggleClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> Adheres to the <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/switch/">Switch WAI-ARIA design pattern </ExitLink>. Toggle at its core functions like a Switch. Toggle is an on-off switch with two states. Switches are similar to checkboxes and toggle buttons, which can also serve as binary inputs. One difference, however, is that switches can only be used for binary input while checkboxes and toggle buttons allow implementations the option of supporting a third middle state. Note: "On/Off" text not used in Toggle switch. ```jsx live () => { const form = useFormV2({ defaultValues: { 'accept-terms': false, }, }); const onSubmit = (data) => { console.log('submitted', data); }; return ( <V2FormProvider state={form} onSubmit={onSubmit}> <V2Toggle label="I agree to the terms and conditions" model="accept-terms" isRequired subText="Read conditions prior to agreeing" validators={{ required: 'You must agree to continue' }} /> <V2Button type="submit" size="$sm" css={{ 'abyss-button-root': { marginTop: '$web.semantic.spacing.scale.md', }, }} > Submit </V2Button> </V2FormProvider> ); }; ``` <h3> Reduced Motion </h3> Animations and transitions that have been changed when a user has `prefers-reduced-motion` set to `reduced`: - transition between on/off state is removed ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Tab', description: 'Moves focus to the first toggle item.', }, { name: 'Space', description: 'When focus is on an item, changes the state of the switch.', }, ]} /> ``` </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={'V2Toggle'} keys={['toggleV2']} /> ``` </Tab> --- id: toggle-group category: Forms title: ToggleGroup description: Combines checkboxes to give multiple options for selection. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=24220-104321 --- <Tab label="Overview"> ```jsx import { ToggleGroup } from '@uhg-abyss/web/ui/ToggleGroup'; ``` ## Usage ```jsx sandbox { component: 'ToggleGroup', inputs: [ { prop: 'label', type: 'string', }, { prop: 'errorMessage', type: 'string', }, { prop: 'subText', type: 'string', }, { prop: 'borderRadius', type: 'string', }, { prop: 'display', type: 'select', defaultValue: 'row', options: [ { label: 'column', value: 'column' }, { label: 'row', value: 'row' }, ], }, { prop: 'hideLabel', type: 'boolean', }, { prop: 'rounded', type: 'boolean', }, ] } () => { const [value, setValue] = useState(['sun']); console.log('value', value); return ( <ToggleGroup label="ToggleGroup Sandbox" onChange={(val) => setValue(val)} value={value} subText="This is subtext" > <ToggleGroup.Toggle label="Sun" value="sun" ariaLabel="Sunday"/> <ToggleGroup.Toggle label="Mon" value="mon" ariaLabel="Monday"/> <ToggleGroup.Toggle label="Tue" value="tue" ariaLabel="Tuesday"/> <ToggleGroup.Toggle label="Wed" value="wed" ariaLabel="Wednesday"/> <ToggleGroup.Toggle label="Thu" value="thu" ariaLabel="Thursday"/> <ToggleGroup.Toggle label="Fri" value="fri" ariaLabel="Friday"/> <ToggleGroup.Toggle label="Sat" value="sat" ariaLabel="Saturday"/> </ToggleGroup> ); }; ``` ## useForm (recommended) Using the `useForm` hook lets the DOM handle form data. ```jsx live () => { const form = useForm({ defaultValues: { 'toggleGroup-form': ['home'], }, }); const onSubmit = (data) => { console.log('submitted', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <ToggleGroup label="ToggleGroup useForm" model="toggleGroup-form" validators={{ required: true }} > <ToggleGroup.Toggle label="One" value="one" /> <ToggleGroup.Toggle label={<IconSymbol icon="home" />} value="home" ariaLabel="home" /> <ToggleGroup.Toggle label="Three" value="three" /> <ToggleGroup.Toggle label="Four" value="four" /> </ToggleGroup> <Button type="submit" style={{ marginTop: 15 }}> Submit </Button> </FormProvider> ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [value, setValue] = useState(['one']); console.log('value', value); return ( <ToggleGroup label="ToggleGroup useState" onChange={(val) => setValue(val)} value={value} > <ToggleGroup.Toggle label="One" value="one" /> <ToggleGroup.Toggle label={<IconSymbol icon="home" />} value="home" ariaLabel="home" /> <ToggleGroup.Toggle label="Three" value="three" /> <ToggleGroup.Toggle label="Four" value="four" /> </ToggleGroup> ); }; ``` ## Label and subtext Label is required, but subtext is not. Set the `label` prop to change the displayed label for the group. Pass `hideLabel` to visibly hide label but retain accessibility. Use the `subText` prop to display helpful text below the `Toggle Group`. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <ToggleGroup label="Label and Subtext" subText="Subtext" model="label-visible-1" > <ToggleGroup.Toggle label="One" value="one" /> <ToggleGroup.Toggle label="Two" value="two" /> </ToggleGroup> <ToggleGroup label="Label only" model="label-visible-2"> <ToggleGroup.Toggle label="One" value="one" /> <ToggleGroup.Toggle label="Two" value="two" /> </ToggleGroup> <ToggleGroup label="Hidden Label" hideLabel subText="Subtext only" model="label-hidden" > <ToggleGroup.Toggle label="One" value="one" /> <ToggleGroup.Toggle label="Two" value="two" /> </ToggleGroup> </FormProvider> ); }; ``` ## Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip) or a [Popover](/web/ui/popover). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <ToggleGroup label="Default Helper" helper="This is a tooltip" model="helper-tooltip" > <ToggleGroup.Toggle label="One" value="one" /> <ToggleGroup.Toggle label="Two" value="two" /> </ToggleGroup> <ToggleGroup label="Custom Helper" helper={ <Popover title="Custom Helper" content="This is a popover with a custom icon" > <IconSymbol icon="help" variant="outlined" color="$success1" size="$sm" /> </Popover> } model="helper-custom" validators={{ required: true }} > <ToggleGroup.Toggle label="One" value="one" /> <ToggleGroup.Toggle label="Two" value="two" /> </ToggleGroup> </FormProvider> ); }; ``` ## Error message Use the `errorMessage` prop to display a custom error message below the toggle group. Note: The errorMessage prop does not work with useForm and is only applicable within our form input components when useState is being utilized. See the [useForm Docs](/web/hooks/use-form#set-error) for example use cases with useForm. ```jsx live () => { const [value, setValue] = useState([]); return ( <ToggleGroup label="Error Message" value={value} onChange={(val) => setValue(val)} errorMessage="Error Message" > <ToggleGroup.Toggle label="One" value="one" /> <ToggleGroup.Toggle label="Two" value="two" /> <ToggleGroup.Toggle label="Three" value="three" /> </ToggleGroup> ); }; ``` ## Descriptors display Use the `descriptorsDisplay` prop to set the orientation of the error message and subtext descriptor content. Available variants include 'column' and 'row'. The default is set to 'row'. Use the [FormProvider](/web/ui/form-provider#descriptors-display) and `descriptorsDisplay` to set the descriptors orientation across an entire form. ```jsx live () => { const [value, setValue] = useState([]); return ( <ToggleGroup value={value} onChange={(val) => setValue(val)} label="Descriptors Display" subText="Subtext Message" errorMessage="Error Message" descriptorsDisplay="column" > <ToggleGroup.Toggle label="One" value="one" /> <ToggleGroup.Toggle label="Two" value="two" /> <ToggleGroup.Toggle label="Three" value="three" /> </ToggleGroup> ); }; ``` ## Rounded Use the `rounded` prop to change the style of the ToggleGroup from Rectangle to `rounded`. The default is squared and set to `false`. ```jsx live () => { const [value, setValue] = useState([]); return ( <ToggleGroup value={value} onChange={(val) => setValue(val)} label="Rounded Display" rounded > <ToggleGroup.Toggle label="1" value="one" /> <ToggleGroup.Toggle label={<IconSymbol icon="home" />} value="home" ariaLabel="home" /> <ToggleGroup.Toggle label="2" value="two" /> </ToggleGroup> ); }; ``` ## Border radius Use the `borderRadius` prop to set to set the border radius of the container, as well as the selected toggle item. There are two preset values you can use, `$md`, and `$lg`, or you can input a custom value. The default value is `$md`. ```jsx live () => { const [mediumGroupValue, setMediumGroupValue] = useState(['one']); const [largeGroupValue, setLargeGroupValue] = useState(['one']); return ( <React.Fragment> <ToggleGroup label="Medium Border Radius - Default" onChange={(value) => setMediumGroupValue(value)} value={mediumGroupValue} > <ToggleGroup.Toggle label="One" value="one" /> <ToggleGroup.Toggle label="Two" value="two" /> <ToggleGroup.Toggle label="Three" value="three" /> </ToggleGroup> <ToggleGroup label="Large Border Radius" onChange={(value) => setLargeGroupValue(value)} value={largeGroupValue} borderRadius="$lg" > <ToggleGroup.Toggle label="One" value="one" /> <ToggleGroup.Toggle label="Two" value="two" /> <ToggleGroup.Toggle label="Three" value="three" /> </ToggleGroup> </React.Fragment> ); }; ``` ## Disabled Set the `isDisabled` prop to `true` to disable all toggle items in the group. Individual toggle items can be disabled by setting `isDisabled` to `true` in their respective `ToggleGroup.Toggle` instead of the outer component. ```jsx live () => { const form = useForm({}); return ( <FormProvider state={form}> <ToggleGroup isDisabled label="All Items Disabled" model="disabled" display="row" > <ToggleGroup.Toggle value="Disabled 1" label="Disabled 1" /> <ToggleGroup.Toggle value="Disabled 2" label="Disabled 2" /> <ToggleGroup.Toggle value="Disabled 3" label="Disabled 3" /> <ToggleGroup.Toggle value="Disabled 4" label="Disabled 4" /> </ToggleGroup> <ToggleGroup label="Individual Items Disabled" model="disabled2" display="row" > <ToggleGroup.Toggle value="Disabled 1" label="Disabled 1" isDisabled /> <ToggleGroup.Toggle value="Enabled 1" label="Enabled 1" /> <ToggleGroup.Toggle value="Disabled 2" label="Disabled 2" isDisabled /> <ToggleGroup.Toggle value="Enabled 2" label="Enabled 2" /> </ToggleGroup> </FormProvider> ); }; ``` ## Display Use the `display` prop to set the direction in which the toggle group appears. The default is set to `'column'`. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <ToggleGroup label="ToggleGroup Row" model="column"> <ToggleGroup.Toggle label="Column A" value="A" /> <ToggleGroup.Toggle label="Column B" value="B" /> </ToggleGroup> <ToggleGroup label="ToggleGroup Column" model="row" display="column"> <ToggleGroup.Toggle label="Row A" value="Row A" /> <ToggleGroup.Toggle label="Row B" value="Row B" /> </ToggleGroup> </FormProvider> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={ToggleGroup} rows={[ { name: 'children', type: 'ReactNode', description: 'The contents of the ToggleGroup component', }, { name: 'label', type: 'string', description: 'Set the label of the ToggleGroup', }, { name: 'helper', type: 'node | string', description: 'Helper element next to label', }, { name: 'value', type: 'array', description: 'Value(s) selected', }, { name: 'model', type: 'string', description: 'Unique identifier used for FormProvider', }, { name: 'errorMessage', type: 'string', description: 'Set the error message', }, { name: 'validators', type: 'shape', description: 'Rules for validation', }, { name: 'display', type: "'row' | 'column'", description: 'Set the direction in which the toggle group is displayed', }, { name: 'borderRadius', type: 'number | string', description: "Set the border radius of the container and the selected toggle item's background", }, { name: 'borderRadiuses', type: 'object', description: 'Set border radius options', }, { name: 'hideLabel', type: 'boolean', description: 'Flag to hide label', }, { name: 'rounded', type: 'boolean', description: "Change the toggle group's style from rectangle to rounded", }, { name: 'isDisabled', type: 'boolean', description: 'Flag to disable all toggle items', }, { name: 'onChange', type: 'function', description: 'Callback fired when the value changes', }, { name: 'onFocus', type: 'function', description: 'Callback fired when the component is focused', }, { name: 'onBlur', type: 'function', description: 'Callback fired when the component is unfocused', }, { name: 'subText', type: 'string', description: 'Set the subtext of the ToggleGroup', }, { name: 'descriptorsDisplay', type: '"row" | "column"', description: 'Set the orientation of descriptor content located below the ToggleGroup', }, ]} /> ``` ```jsx render <Docs.PropsTable of={ToggleGroup.Toggle} rows={[ { name: 'children', type: 'ReactNode', description: 'The element the ToggleGroup.Toggle wraps', }, { name: 'isDisabled', type: 'boolean', description: 'Flag to disable Toggle', }, { name: 'label', type: 'string', description: 'Set the label of Toggle', }, { name: 'value', type: 'string', description: 'Value of the Toggle', }, { name: 'ariaLabel', type: 'string', description: `'aria-label' for Toggle with abbreviated word or icon`, }, ]} /> ``` ```jsx render <Docs.ClassesTable of={ToggleGroup} rows={[ { name: 'toggle-group-root', description: 'ToggleGroup root element', }, { name: 'toggle-group-label', description: 'ToggleGroup label', }, { name: 'toggle-group-container', description: 'ToggleGroup container', }, { name: 'toggle-group-descriptors', description: 'ToggleGroup descriptors', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={ToggleGroup.Toggle} rows={[ { name: 'toggle-input-root', description: 'Toggle input root', }, { name: 'toggle-input-checkbox', description: 'Toggle input type', }, { name: 'toggle-input-label', description: 'Toggle input label', }, ]} /> ``` </Tab> <Tab label="Accessibility"> ToggleGroup at its core functions like a CheckBox Group. A CheckBox group is a set of checkable checkboxes, where more than one of the checkboxes can be checked at a time. Some implementations may initialize the set with all checkboxes in the unchecked state in order to force the user to check one of the checkboxes before moving past a certain point in the workflow. Use the `ariaLabel` prop in `ToggleGroup.Toggle` when using abbreviated words or icons. This will include an "aria-label" for screen readers. ```jsx live () => { const [value, setValue] = useState(['one']); return ( <ToggleGroup label="Accessibility Practice" onChange={(val) => setValue(val)} value={value} subText="Utilize the Keyboard Interaction table below to test the components accessibility." > <ToggleGroup.Toggle label="Sun" value="sun" ariaLabel="Sunday" /> <ToggleGroup.Toggle label="Mon" value="mon" ariaLabel="Monday" /> <ToggleGroup.Toggle label="Tue" value="tue" ariaLabel="Tuesday" /> <ToggleGroup.Toggle label="Wed" value="wed" ariaLabel="Wednesday" /> <ToggleGroup.Toggle label="Thu" value="thu" ariaLabel="Thursday" /> <ToggleGroup.Toggle label="Fri" value="fri" ariaLabel="Friday" /> <ToggleGroup.Toggle label="Sat" value="sat" ariaLabel="Saturday" /> </ToggleGroup> ); }; ``` ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Tab', description: 'Moves focus to first element and then next items in the group Tab sequence', }, { name: 'Space', description: 'When focus is on an unchecked checkbox item, checks it.', }, ]} /> ``` </Tab> --- id: toggle-switch category: Forms title: ToggleSwitch description: Used to switch between on and off between 2 modes. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=510-11906 --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="ToggleSwitch"></Docs.V2MigrationBanner> ``` ```jsx import { ToggleSwitch } from '@uhg-abyss/web/ui/ToggleSwitch'; ``` ```jsx sandbox { component: 'ToggleSwitch', inputs: [ { prop: 'label', type: 'string', }, { prop: 'size', type: 'string' }, { prop: 'isDisabled', type: 'boolean' }, ] } () => { const [isChecked, setChecked] = useState(true); return ( <ToggleSwitch label="Label" isChecked={isChecked} onChange={e => setChecked(e.target.checked)} /> ); }; ``` ## useForm (recommended) Using the `useForm` hook lets the DOM handle form data. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('submitted', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <ToggleSwitch label="Form ToggleSwitch" model="accept-terms" /> </FormProvider> ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [isChecked, setChecked] = useState(false); return ( <ToggleSwitch label="State ToggleSwitch" isChecked={isChecked} onChange={(e) => setChecked(e.target.checked)} /> ); }; ``` ## Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip) or a [Popover](/web/ui/popover). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <ToggleSwitch label="Default Helper" helper="This is a tooltip" model="helper-tooltip" /> <ToggleSwitch label="Custom Helper" helper={ <Popover title="Custom Helper" content="This is a popover with a custom icon" > <IconSymbol icon="help" variant="outlined" color="$success1" size="$sm" /> </Popover> } model="helper-custom" validators={{ required: true }} /> </FormProvider> ); }; ``` ## Disabled Use the `isDisabled` property to disable the `ToggleSwitch`. The default is set to `false`. ```jsx live () => { const form = useForm(); const onSubmit = (data) => { console.log('submitted', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <ToggleSwitch isDisabled label="Disabled ToggleSwitch" model="accept-terms" /> </FormProvider> ); }; ``` ## Size Use the `size` property to set the size of the `ToggleSwitch`. Can use predefined sizes or custom number to set size. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <ToggleSwitch label="Small" size="sm" model="size-sm" /> <ToggleSwitch label="Medium - Default" model="size-md" /> <ToggleSwitch label="Large" size="lg" model="size-lg" /> <ToggleSwitch label="Custom / 30px" size="30px" model="size-custom" /> </FormProvider> ); }; ``` ## With text Adding labels to the toggle, implements text inside the toggle container ```jsx live () => { return ( <Layout.Group> <ToggleSwitch model="network-status" text={['Active Toggle', 'Inactive Toggle']} ></ToggleSwitch> <ToggleSwitch model="network-status" text={['In-network', 'Out-of-network']} ></ToggleSwitch> <ToggleSwitch model="network-status" text={['On', 'Off']}></ToggleSwitch> </Layout.Group> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={ToggleSwitch} rows={[ { name: 'children', type: 'ReactNode', description: 'The contents of the toggle switch component', }, { name: 'onChange', type: 'function', description: 'Callback fired everytime the value changes', }, { name: 'onFocus', type: 'function', description: 'Callback fired everytime the component is focused', }, { name: 'onBlur', type: 'function', description: 'Callback fired everytime the component is unfocused', }, // { // name: 'text', // type: 'bool', // description: ' true | false', // }, { name: 'borderRadius', type: 'string', description: 'Set the border radisu', }, { name: 'label', type: 'string', description: 'Label of the toggle switch', }, { name: 'hideLabel', type: 'boolean', description: 'Flag to hide label', }, { name: 'helper', type: 'node | string', description: 'Helper element next to label', }, { name: 'isChecked', type: 'boolean', description: 'Flag to turn toggle switch on or off', }, { name: 'isDisabled', type: 'boolean', description: 'Flag to enable/disable the toggle switch. If true, the toggle switch will be disabled', }, { name: 'model', type: 'string', description: 'Unique identifier used for FormProvider', }, { name: 'size', type: 'number | string', description: 'Height and width of the toggle switch', }, { name: 'sizes', type: 'shape', description: 'The potential size options for the toggle switch', }, // { // name: 'text', // type: 'boolean', // description: 'Set the text displayed in toggle switch', // }, ]} /> ``` ```jsx render <Docs.ClassesTable of={ToggleSwitch} rows={[ { name: 'toggle-switch-root', description: 'Toggle Switch root element', }, { name: 'toggle-switch-label', description: 'Label', }, { name: 'toggle-switch-container', description: 'Container', }, // { // name: 'toggle-switch-text', // description: 'Text content', // }, { name: 'toggle-switch', description: 'Toggle input', }, ]} /> ``` </Tab> <Tab label="Accessibility"> Adheres to the <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/switch/">Switch WAI-ARIA design pattern </ExitLink>. ToggleSwitch at its core functions like a Switch. Toggle switch is an on-off switch with two states. Switches are similar to checkboxes and toggle buttons, which can also serve as binary inputs. One difference, however, is that switches can only be used for binary input while checkboxes and toggle buttons allow implementations the option of supporting a third middle state. Note: "On/Off" text not used in Toggle switch. ```jsx live () => { const [isChecked, setChecked] = useState(true); return ( <ToggleSwitch label="Play ring tone" helper="Only on this device" isChecked={isChecked} onChange={(e) => setChecked(e.target.checked)} /> ); }; ``` <h3> Reduced Motion </h3> Animations and transitions that have been changed when a user has `prefers-reduced-motion` set to `reduced`: - transition between on/off state is removed ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Tab', description: 'Moves focus to either the first toggle switch item or the helper prop to display a help icon next to the label', }, { name: 'Space', description: 'When focus is on an item, changes the state of the switch. Also when focus is on a custom helper, it opens up a popover with title and content', }, ]} /> ``` </Tab> --- id: toggle-tabs category: Forms title: ToggleTabs description: Combines radio buttons and tabs to give multiple options as one element. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=3697-25496 --- <Tab label="Overview"> ```jsx import { ToggleTabs } from '@uhg-abyss/web/ui/ToggleTabs'; ``` ## Usage ```jsx sandbox { component: 'ToggleTabs', inputs: [ { prop: 'label', type: 'string', }, { prop: 'errorMessage', type: 'string', }, { prop: 'subText', type: 'string', }, { prop: 'borderRadius', type: 'string', }, { prop: 'display', type: 'select', options: [ { label: 'column', value: 'column' }, { label: 'row', value: 'row' }, ], }, { prop: 'hideLabel', type: 'boolean', }, { prop: 'fullWidth', type: 'boolean' }, ] } () => { const [toggleValue, setToggleValue] = useState('low-d'); console.log('toggleValue', toggleValue); return ( <ToggleTabs label="ToggleTabs Sandbox" onChange={(e) => setToggleValue(e.target.value)} value={toggleValue} subText="This is subtext" > <ToggleTabs.Tab label="Low-Deductible" value="low-d" /> <ToggleTabs.Tab label="Bind" value="bind" /> <ToggleTabs.Tab label="Balanced" value="bal" /> <ToggleTabs.Tab label="Low-Premium" value="low-p" /> <ToggleTabs.Tab label="Full-Coverage" value="full" /> <ToggleTabs.Tab label="No Coverage" value="none" /> </ToggleTabs> ); }; ``` ## useForm (recommended) Using the `useForm` hook lets the DOM handle form data. ```jsx live () => { const form = useForm({ defaultValues: { 'toggle-form': 'two', }, }); const onSubmit = (data) => { console.log('submitted', data); }; return ( <FormProvider state={form} onSubmit={onSubmit}> <ToggleTabs label="ToggleTabs useForm" model="toggle-form" validators={{ required: true }} > <ToggleTabs.Tab label="One" value="one" /> <ToggleTabs.Tab label={<IconSymbol icon="home" />} value="two" ariaLabel="home" /> <ToggleTabs.Tab label="Three" value="three" /> <ToggleTabs.Tab label="Four" value="four" /> </ToggleTabs> <Button type="submit" style={{ marginTop: 15 }}> Submit </Button> </FormProvider> ); }; ``` ## useState Using the `useState` hook gets values from the component state. ```jsx live () => { const [toggleValue, setToggleValue] = useState('one'); console.log('toggleValue', toggleValue); return ( <ToggleTabs label="ToggleTabs useState" onChange={(e) => setToggleValue(e.target.value)} value={toggleValue} > <ToggleTabs.Tab label="One" value="one" /> <ToggleTabs.Tab label={<IconSymbol icon="home" />} value="two" ariaLabel="home" /> <ToggleTabs.Tab label="Three" value="three" /> <ToggleTabs.Tab label="Four" value="four" /> </ToggleTabs> ); }; ``` ## Label and subtext Label is required, but subtext is not. Set the `label` prop to change the displayed label for the group. Pass `hideLabel` to visibly hide label but retain accessibility. Use the `subText` prop to display helpful text below the tabs. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <ToggleTabs label="Label and Subtext" subText="Subtext" model="label-visible-1" > <ToggleTabs.Tab label="One" value="one" /> <ToggleTabs.Tab label="Two" value="two" /> </ToggleTabs> <ToggleTabs label="Label only" model="label-visible-2"> <ToggleTabs.Tab label="One" value="one" /> <ToggleTabs.Tab label="Two" value="two" /> </ToggleTabs> <ToggleTabs label="Hidden Label" hideLabel subText="Subtext only" model="label-hidden" > <ToggleTabs.Tab label="One" value="one" /> <ToggleTabs.Tab label="Two" value="two" /> </ToggleTabs> </FormProvider> ); }; ``` ## Helper Use the `helper` prop to display a help icon next to the label. Simply passing a string value will render the default helper, a [Tooltip](/web/ui/tooltip) containing that string. The helper can be customized by passing in a node. It is recommended to use either a [Tooltip](/web/ui/tooltip) or a [Popover](/web/ui/popover). See [When should I use a Tooltip vs. a Popover?](/web/ui/tooltip/#when-should-i-use-a-tooltip-vs-a-popover) for more information on best practices regarding the two. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <ToggleTabs label="Default Helper" helper="This is a tooltip" model="helper-tooltip" > <ToggleTabs.Tab label="One" value="one" /> <ToggleTabs.Tab label="Two" value="two" /> </ToggleTabs> <ToggleTabs label="Custom Helper" helper={ <Popover title="Custom Helper" content="This is a popover with a custom icon" > <IconSymbol icon="help" variant="outlined" color="$success1" size="$sm" /> </Popover> } model="helper-custom" validators={{ required: true }} > <ToggleTabs.Tab label="One" value="one" /> <ToggleTabs.Tab label="Two" value="two" /> </ToggleTabs> </FormProvider> ); }; ``` ## Error message Use the `errorMessage` prop to display a custom error message below the tabs. Note: The errorMessage prop does not work with useForm and is only applicable within our form input components when useState is being utilized. See the [useForm Docs](/web/hooks/use-form#set-error) for example use cases with useForm. ```jsx live () => { const [toggleValue, setToggleValue] = useState(''); return ( <ToggleTabs label="Error Message" value={toggleValue} onChange={(e) => setToggleValue(e.target.value)} errorMessage="Error Message" > <ToggleTabs.Tab label="One" value="one" /> <ToggleTabs.Tab label="Two" value="two" /> <ToggleTabs.Tab label="Three" value="three" /> </ToggleTabs> ); }; ``` ## Descriptors display Use the `descriptorsDisplay` prop to set the orientation of the error message and subtext descriptor content. Available variants include 'column' and 'row'. The default is set to 'row'. Use the [FormProvider](/web/ui/form-provider#descriptors-display) and `descriptorsDisplay` to set the descriptors orientation across an entire form. ```jsx live () => { const [toggleValue, setToggleValue] = useState(''); return ( <ToggleTabs value={toggleValue} onChange={(e) => setToggleValue(e.target.value)} label="Descriptors Display" subText="Subtext Message" errorMessage="Error Message" descriptorsDisplay="column" > <ToggleTabs.Tab label="One" value="one" /> <ToggleTabs.Tab label="Two" value="two" /> <ToggleTabs.Tab label="Three" value="three" /> </ToggleTabs> ); }; ``` ## Border radius Use the `borderRadius` prop to set to set the border radius of the container, as well as the selected tab. There are three preset values you can use, `$sm`, `$md`, and `$lg`, or you can input a custom value. The default value is `$md`. ```jsx live () => { const [toggleValue1, setToggleValue1] = useState('one'); const [toggleValue2, setToggleValue2] = useState('one'); const [toggleValue3, setToggleValue3] = useState('one'); return ( <React.Fragment> <ToggleTabs label="Small Border Radius" onChange={(e) => setToggleValue1(e.target.value)} value={toggleValue1} borderRadius="$sm" > <ToggleTabs.Tab label="One" value="one" /> <ToggleTabs.Tab label="Tab Number Two" value="two" /> <ToggleTabs.Tab label="Three" value="three" /> </ToggleTabs> <ToggleTabs label="Medium Border Radius - Default" onChange={(e) => setToggleValue2(e.target.value)} value={toggleValue2} > <ToggleTabs.Tab label="One" value="one" /> <ToggleTabs.Tab label="Tab Number Two" value="two" /> <ToggleTabs.Tab label="Three" value="three" /> </ToggleTabs> <ToggleTabs label="Large Border Radius" onChange={(e) => setToggleValue3(e.target.value)} value={toggleValue3} borderRadius="$lg" > <ToggleTabs.Tab label="One" value="one" /> <ToggleTabs.Tab label="Tab Number Two" value="two" /> <ToggleTabs.Tab label="Three" value="three" /> </ToggleTabs> </React.Fragment> ); }; ``` ## Disabled Set the `isDisabled` prop to `true` to disable all tabs in the group. Individual tabs can be disabled by setting `isDisabled` to `true` in their respective `ToggleTabs.Tab` instead of the outer component. ```jsx live () => { const form = useForm({}); return ( <FormProvider state={form}> <ToggleTabs isDisabled label="All Tabs Disabled" model="disabled"> <ToggleTabs.Tab value="dogs" label="Disabled 1" /> <ToggleTabs.Tab value="cats" label="Disabled 2" /> <ToggleTabs.Tab value="cats1" label="Disabled 3" /> <ToggleTabs.Tab value="cats2" label="Disabled 4" /> </ToggleTabs> <ToggleTabs label="Individual Tabs Disabled" model="disabled2"> <ToggleTabs.Tab value="dogs" label="Disabled 1" isDisabled /> <ToggleTabs.Tab value="cats" label="Enabled 1" /> <ToggleTabs.Tab value="cats1" label="Disabled 2" isDisabled /> <ToggleTabs.Tab value="cats2" label="Enabled 2" /> </ToggleTabs> </FormProvider> ); }; ``` ## Display Use the `display` prop to set the direction in which the tabs appear. The default is set to `'row'`. ```jsx live () => { const form = useForm(); return ( <FormProvider state={form}> <ToggleTabs label="ToggleTabs Column" model="column" display="column"> <ToggleTabs.Tab label="Column A" value="A" /> <ToggleTabs.Tab label="Column B" value="B" /> </ToggleTabs> <ToggleTabs label="ToggleTabs Row" model="row"> <ToggleTabs.Tab label="Row A" value="A" /> <ToggleTabs.Tab label="Row B" value="B" /> </ToggleTabs> </FormProvider> ); }; ``` </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={ToggleTabs} rows={[ { name: 'children', type: 'ReactNode', description: 'The contents of the ToggleTabs component', }, { name: 'label', type: 'string', description: 'Set the label of the ToggleTabs', }, { name: 'helper', type: 'node | string', description: 'Helper element next to label', }, { name: 'value', type: 'string', description: 'Value that is selected', }, { name: 'model', type: 'string', description: 'Unique identifier used for FormProvider', }, { name: 'errorMessage', type: 'string', description: 'Set the error message', }, { name: 'validators', type: 'shape', description: 'Rules for validation', }, { name: 'display', type: "'row' | 'column'", description: 'Set the direction in which the tabs are displayed', }, { name: 'borderRadius', type: 'number | string', description: "Set the border radius of the container and the selected tab's background", }, { name: 'borderRadiuses', type: 'object', description: 'Set border radius options', }, { name: 'fullWidth', type: 'boolean', description: 'Flag to make the tabs take up the full width of the container', }, { name: 'hideLabel', type: 'boolean', description: 'Flag to hide label', }, { name: 'isDisabled', type: 'boolean', description: 'Flag to disable all tabs', }, { name: 'onChange', type: 'function', description: 'Callback fired when the value changes', }, { name: 'onFocus', type: 'function', description: 'Callback fired when the component is focused', }, { name: 'onBlur', type: 'function', description: 'Callback fired when the component is unfocused', }, { name: 'subText', type: 'string', description: 'Set the subtext of the ToggleTabs', }, { name: 'descriptorsDisplay', type: '"row" | "column"', description: 'Set the orientation of descriptor content located below the ToggleTabs', }, ]} /> ``` ```jsx render <Docs.PropsTable of={ToggleTabs.Tab} rows={[ { name: 'checked', type: 'boolean', description: 'Flag to see if tab is checked', }, { name: 'children', type: 'ReactNode', description: 'The element the tab wraps', }, { name: 'isDisabled', type: 'boolean', description: 'Flag to see if tab is disabled', }, { name: 'label', type: 'string', description: 'Set the label of tab', }, { name: 'value', type: 'string', description: 'Value of the tab', }, { name: 'ariaLabel', type: 'string', description: `'aria-label' for Tab with abbreviated word or icons`, }, ]} /> ``` ```jsx render <Docs.ClassesTable of={ToggleTabs} rows={[ { name: 'toggle-tabs-root', description: 'ToggleTabs root element', }, { name: 'toggle-tabs-label', description: 'ToggleTabs label', }, { name: 'toggle-tabs-container', description: 'ToggleTabs container', }, { name: 'toggle-tabs-selected-background', description: 'Background that appears on the selected tab', }, { name: 'toggle-tabs-descriptors', description: 'ToggleTabs descriptors', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={ToggleTabs.Tab} rows={[ { name: 'tab-root', description: 'Tab Root', }, { name: 'tab', description: 'Tab', }, { name: 'tab-label', description: 'Tab Label', }, ]} /> ``` </Tab> <Tab label="Accessibility"> ToggleTabs at its core functions like a Radio Group. A radio group is a set of checkable buttons, known as radio buttons, where no more than one of the buttons can be checked at a time. Some implementations may initialize the set with all buttons in the unchecked state in order to force the user to check one of the buttons before moving past a certain point in the workflow. Use the `ariaLabel` prop in `ToggleTabs.Tab` when using abbreviated words or icons. This will include an "aria-label" for screen readers. Adheres to the <ExitLink href="https://www.w3.org/TR/wai-aria-practices-1.2/#toggletabs"> WAI-ARIA design pattern</ExitLink>. ```jsx live () => { const [toggleValue, setToggleValue] = useState('one'); return ( <ToggleTabs label="Accessibility Practice" onChange={(e) => setToggleValue(e.target.value)} value={toggleValue} subText="Utilize the Keyboard Interaction table below to test the components accessibility." > <ToggleTabs.Tab label="One" value="one" /> <ToggleTabs.Tab label="Two" value="two" /> <ToggleTabs.Tab label="Three" value="three" /> <ToggleTabs.Tab label="Four" value="four" /> </ToggleTabs> ); }; ``` <h3> Reduced Motion </h3> Animations and transitions that have been changed when a user has `prefers-reduced-motion` set to `reduced`: - Removed animation of active background color upon switching tabs ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Tab', description: 'Moves focus to either the checked radio item or the first radio item in the group.', }, { name: 'Space', description: 'When focus is on an unchecked radio item, checks it.', }, { name: 'Enter', description: 'When focus is on an unchecked radio item, checks it.', }, { name: 'Arrow Down', description: 'Moves focus to the next radio item in the group.', }, { name: 'Arrow Right', description: 'Moves focus to the next radio item in the group.', }, { name: 'Arrow Up', description: 'Moves focus to the previous radio item in the group.', }, { name: 'Arrow Left', description: 'Moves focus to the previous radio item in the group.', }, ]} /> ``` </Tab> --- id: tooltip-v2 category: Overlay title: V2Tooltip description: A contextual text bubble that displays a description for an element that appears on pointer hover or keyboard focus. design: https://www.figma.com/design/TlKDpeSY68pCS8OyghIiCM/Docs---Web-Global?node-id=10565-18739 subDirectory: Tooltip/v2 sourceIsTS: true --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="Tooltip"></Docs.V2MigrationBanner> ``` ```jsx import { V2Tooltip } from '@uhg-abyss/web/ui/Tooltip'; ``` ```jsx sandbox { component: 'V2Tooltip', inputs: [ { prop: 'content', type: 'string', }, { prop: 'position', type: 'select', options: [ { label: 'top', value: 'top' }, { label: 'bottom', value: 'bottom' }, { label: 'left', value: 'left' }, { label: 'right', value: 'right' }, ], }, { prop: 'variant', type: 'select', options: [ { label: 'gray', value: 'gray' }, { label: 'white', value: 'white' }, ], }, { prop: 'delayDuration', type: 'number' }, ], } <V2Tooltip content="Information goes here"> <V2Button aria-label="Tooltip information" icon={{ icon: 'question_mark', position: 'icon-only' }} /> </V2Tooltip> ``` ## Content Use the `content` prop to insert a text description that appears on pointer hover or keyboard focus. ```jsx live <Layout.Group grow> <V2Tooltip content="Use this button to save information in your profile, after that you will be able to access it any time and share it via email."> <V2Button>Save to profile</V2Button> </V2Tooltip> <V2Tooltip content="Click to view more options"> <V2Button aria-label="More options" icon={{ icon: 'more_vert', position: 'icon-only' }} /> </V2Tooltip> <V2Tooltip content="Customize user settings"> <V2Button icon={{ icon: 'settings', position: 'trailing' }}> Settings </V2Button> </V2Tooltip> </Layout.Group> ``` ## asChild Using `asChild` prop will merge the original component props with the props of the supplied element/component and change the underlying DOM node. The default value is `true`. Set `asChild` to `false` to render tooltip on static elements. ```jsx live <Layout.Group grow> <V2Tooltip content="Tooltip on dynamic element."> <V2Button>Hover me!</V2Button> </V2Tooltip> <V2Tooltip content="Tooltip on static element." asChild={false}> Hover me! </V2Tooltip> </Layout.Group> ``` ## Position Use the `position` prop to change the position of the tooltip. Options include `'left'`, `'right'`, `'top'`, and `'bottom'`. The default position is `'bottom'`. Note: When the tooltip cannot fit in the screen at the provided position, it will dynamically change orientation to fit. ```jsx live <Layout.Group grow> <V2Tooltip content="Bottom" position="bottom"> <V2Button aria-label="Keyboard arrow down" icon={{ icon: 'keyboard_arrow_down', position: 'icon-only' }} /> </V2Tooltip> <V2Tooltip content="Left" position="left"> <V2Button aria-label="Keyboard arrow left" icon={{ icon: 'keyboard_arrow_left', position: 'icon-only' }} /> </V2Tooltip> <V2Tooltip content="Top" position="top"> <V2Button aria-label="Keyboard arrow top" icon={{ icon: 'keyboard_arrow_up', position: 'icon-only' }} /> </V2Tooltip> <V2Tooltip content="Right" position="right"> <V2Button aria-label="Keyboard arrow right" icon={{ icon: 'keyboard_arrow_right', position: 'icon-only' }} /> </V2Tooltip> </Layout.Group> ``` ## Delay duration Use the `delayDuration` prop to control the time it takes for the tooltip to open. The default is `300` milliseconds. Setting the `delayDuration` to `0` will render tooltip instantly. Maximum `delayDuration` is `700` milliseconds. ```jsx live <Layout.Group grow> <V2Tooltip content="Delay: 0" delayDuration={0}> <V2Button aria-label="Tooltip delay 0ms" icon={{ icon: 'timer', position: 'icon-only' }} /> </V2Tooltip> <V2Tooltip content="Delay: 300" delayDuration={300}> <V2Button aria-label="Tooltip delay 300ms" icon={{ icon: 'timer', position: 'icon-only' }} /> </V2Tooltip> <V2Tooltip content="Delay: 700" delayDuration={700}> <V2Button aria-label="Tooltip delay 700ms" icon={{ icon: 'timer', position: 'icon-only' }} /> </V2Tooltip> </Layout.Group> ``` ## Variant Use the `variant` prop to choose the color variant of the tooltip. The default is `'gray'`, the other option is `'white'`, which sets a white background. ```jsx live <Layout.Group grow> <V2Tooltip content="Gray background"> <V2Button>Gray Variant</V2Button> </V2Tooltip> <Box color="$primary1"> <V2Tooltip content="White background" variant="white"> <V2Button color="inverse">White Variant</V2Button> </V2Tooltip> </Box> </Layout.Group> ``` ## When should I use a tooltip vs a popover? Glad you asked! There are several considerations when deciding between a [Tooltip](/web/ui/tooltip-v2) or a [Popover](/web/ui/popover): ### Purpose of content - A [Tooltip](/web/ui/tooltip-v2) is a hint or a tip about what an interactive element does. Tooltips are meant to help clarify or provide supplementary instruction for an element on hover or upon receiving focus. They should not be used to add additional content nor should they include interactive elements such as links. Tooltips should not receive mouse or keyboard focus. Try to position tooltips so they do not overlap and cover other content on the screen. This helps keep all content readable by all users and reduces concerns regarding <ExitLink href="https://www.w3.org/WAI/WCAG21/Understanding/content-on-hover-or-focus.html">WCAG 2.1 SC 1.4.13: Content on Hover or Focus</ExitLink> - A [Popover](/web/ui/popover) should be used to provide additional content to static text, such as definitions of words, informational blurbs, or additional product details. They can receive focus and can contain links and other interactive elements. ### Size of content - Since [Tooltips](/web/ui/tooltip-v2) are only meant to tell the purpose of an element they should be short and to the point, for example: "Click X to do X" or "User post count". - [Popovers](/web/ui/popover), on the other hand, can be much more verbose, they can include a heading, lines of text in the body, links, etc. ### Interactions - [Tooltips](/web/ui/tooltip-v2) should only be visible on mouse hover or upon receiving focus. For this reason, if you need to be able to read the content while interacting with other parts of the page then a [Tooltip](/web/ui/tooltip-v2) will not work. They should be dismissible using the "escape" key. They should be used on interactive elements where a mouse click or keyboard activation would otherwise trigger the elements primary function. - [Popovers](/web/ui/popover) must be triggered to appear, whether via mouse click or via keyboard navigation. They must be dismissible, whether by clicking on other parts of the page, clicking the [Popover](/web/ui/popover) target, or a specific close button/icon (depending on implementation). For this reason, you can set up a [Popover](/web/ui/popover) to allow you to interact with other elements on the page while still being able to read its content. On top of this, since [Popovers](/web/ui/popover) will remain open when mousing out of their target, you can add additional buttons or interactions within them. ### Mobile screens Tooltips only work on mouse hover (or keyboard focus). Since mobile users can't hover, the tooltip won't appear, rendering it ineffective and leading to a poor user experience where essential information might be inaccessible. Instead, we recommend using our [Popover](/web/ui/popover) component for a better mobile experience. Also, bear in mind that mobile screens are smaller, so please keep your content concise to ensure readability. ### Conclusion If you want to give a short hint or supplemental instructions for an interactive element (such as a submit button), use a [Tooltip](/web/ui/tooltip-v2). If you want to add additional content to a static element that might include headings, body text, links, etc, and you need the content to remain open even after mousing away or the element losing focus, then use a [Popover](/web/ui/popover). It should be noted that any vital information users need to complete an action or make a decision should be displayed directly in the page text or button label, rather than a [Tooltip](/web/ui/tooltip-v2) or a [Popover](/web/ui/popover). Critical information hidden in a [Tooltip](/web/ui/tooltip-v2) or a [Popover](/web/ui/popover) might not be discovered by all users and could create accessibility issues. </Tab> <Tab label="Integration"> ```jsx render <Docs.V2WebPropsTable title="V2Tooltip" propTypeName="TooltipProps" showAbyssDefaultTypes /> ``` ```jsx render <Docs.V2ClassesTable title="V2Tooltip" classes={[TooltipClassesMetadata]} /> ``` </Tab> <Tab label="Accessibility"> Tooltips provide contextual information about an element when that owning element receives focus or is hovered over, but are otherwise not visible on the page. While a Tooltip can be placed on any content, they are intended to be used for controls or small visual elements, such as providing additional content for icons with a brief label (or no label at all, which is not accessible!). From an accessibility and usability perspective, try to position tooltips so they do not overlap and cover other content on the screen. This helps keep all content readable by all users and reduces concerns regarding <ExitLink href="https://www.w3.org/WAI/WCAG21/Understanding/content-on-hover-or-focus.html">WCAG 2.1 SC 1.4.13: Content on Hover or Focus</ExitLink>. Instead of using tooltips and hiding important information, if you have the space, consider writing clear, succinct, always-visible descriptions such as labels and body text. Check out the <ExitLink href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/tooltip_role">Mozilla `tooltip` role</ExitLink> docs to learn more. Adheres to the <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/">Tooltip WAI-ARIA design pattern</ExitLink>. ```jsx live <Layout.Group> <V2Tooltip content="Contact Us"> <V2Button aria-label="Contact us" icon={{ icon: 'speaker_notes', position: 'icon-only' }} /> </V2Tooltip> </Layout.Group> ``` ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Tab', description: 'Opens/closes the tooltip without delay.', }, { name: 'Escape', description: 'If open, closes the tooltip without delay.', }, ]} /> ``` </Tab> <Tab label="Tokens"> <h2> Component Tokens </h2> Note: Click on the token row to copy the token to your clipboard. ```jsx render <Docs.ComponentTokensTable of={V2Tooltip} keys={['tooltipV2']} /> ``` </Tab> --- id: tooltip category: Overlay title: Tooltip description: A contextual text bubble that displays a description for an element that appears on pointer hover or keyboard focus. design: https://www.figma.com/design/tk08Md4NBBVUPNHQYthmqp/Abyss-Web-1.0?node-id=12502-49489 subDirectory: Tooltip/v1 --- <Tab label="Overview"> ```jsx render <Docs.V2MigrationBanner v1ComponentName="Tooltip"></Docs.V2MigrationBanner> ``` ```jsx import { Tooltip } from '@uhg-abyss/web/ui/Tooltip'; ``` <br /> ```jsx sandbox { component: 'Tooltip', inputs: [ { prop: 'content', type: 'string', defaultValue: 'When should I use a tooltip vs a popover?', }, { prop: 'position', type: 'select', options: [ { label: 'top', value: 'top' }, { label: 'bottom', value: 'bottom' }, { label: 'left', value: 'left' }, { label: 'right', value: 'right' }, ], }, { prop: 'positionOffset', type: 'number', }, { prop: 'align', type: 'select', options: [ { label: 'start', value: 'start' }, { label: 'center', value: 'center' }, { label: 'end', value: 'end' }, ], }, { prop: 'delayDuration', type: 'number' }, { prop: 'hideArrow', type: 'boolean', }, { prop: 'asChild', type: 'boolean', }, ], } <Tooltip> <Button aria-label="Tooltip information" rounded> <IconSymbol icon="question_mark" color="$white" /> </Button> </Tooltip> ``` ## Content Use the `content` prop to insert a text description that appears on pointer hover or keyboard focus. ```jsx live <Layout.Group grow> <Tooltip content="Use this button to save information in your profile, after that you will be able to access it any time and share it via email."> <Button>Save to profile</Button> </Tooltip> <Tooltip content="Click to view more options"> <Button aria-label="More options" rounded> <IconSymbol icon="more_vert" color="$primary2" /> </Button> </Tooltip> <Tooltip content="Customize user settings"> <Button after={<IconSymbol icon="settings" color="$primary2" />}> Settings </Button> </Tooltip> </Layout.Group> ``` ## asChild Using `asChild` prop will merge the original component props with the props of the supplied element/component and change the underlying DOM node. The default value is `true`. Set `asChild` to `false` to render tooltip on static elements. ```jsx live <Layout.Group grow> <Tooltip content="Tooltip on dynamic element."> <Button>Hover me!</Button> </Tooltip> <Tooltip content="Tooltip on static element." asChild={false}> Hover me! </Tooltip> </Layout.Group> ``` ## Position Use the `position` prop to change the position of the tooltip. Options include `'left'`, `'right'`, `'top'`, and `'bottom'`. The default position is `'bottom'`. ```jsx live <Layout.Group grow> <Tooltip content="Bottom" position="bottom"> <Button aria-label="Keyboard arrow down" rounded> <IconSymbol icon="keyboard_arrow_down" color="$primary2" /> </Button> </Tooltip> <Tooltip content="Left" position="left"> <Button aria-label="Keyboard arrow left" rounded> <IconSymbol icon="keyboard_arrow_left" color="$primary2" /> </Button> </Tooltip> <Tooltip content="Top" position="top"> <Button aria-label="Keyboard arrow up" rounded> <IconSymbol icon="keyboard_arrow_up" color="$primary2" /> </Button> </Tooltip> <Tooltip content="Right" position="right"> <Button aria-label="Keyboard arrow right" rounded> <IconSymbol icon="keyboard_arrow_right" color="$primary2" /> </Button> </Tooltip> </Layout.Group> ``` ## Position offset Use the `positionOffset` prop to change the offset position of the popover. The default value is `4`. Maximum `positionOffset` is `16`. ```jsx live <Layout.Group grow> <Tooltip content="Offset: 4" positionOffset={4}> <Button>Offset: 4</Button> </Tooltip> <Tooltip content="Offset: 8" positionOffset={8}> <Button>Offset: 8</Button> </Tooltip> <Tooltip content="Offset: 16" positionOffset={16}> <Button>Offset: 16</Button> </Tooltip> </Layout.Group> ``` ## Align Use the `align` prop to set the side of the anchor to render against when open. Options include `'start'`, `'center'`, and `'end'`. The default alignment is `center`. ```jsx live <Layout.Group grow> <Tooltip content="Align: Start" align="start"> <Button>Start</Button> </Tooltip> <Tooltip content="Align: Center" align="center"> <Button>Center</Button> </Tooltip> <Tooltip content="Align: End" align="end"> <Button>End</Button> </Tooltip> </Layout.Group> ``` ## Delay duration Use the `delayDuration` prop to control the time it takes for the tooltip to open. The default is `300` milliseconds. Setting the `delayDuration` to `0` will render tooltip instantly. Maximum `delayDuration` is `700` milliseconds. ```jsx live <Layout.Group grow> <Tooltip content="Delay: 0" delayDuration={0}> <Button aria-label="Tooltip deplay 0ms" rounded> <IconSymbol icon="timer" color="$primary2" /> </Button> </Tooltip> <Tooltip content="Delay: 300" delayDuration={300}> <Button aria-label="Tooltip deplay 300ms" rounded> <IconSymbol icon="timer" color="$primary2" /> </Button> </Tooltip> <Tooltip content="Delay: 700" delayDuration={700}> <Button aria-label="Tooltip deplay 700ms" rounded> <IconSymbol icon="timer" color="$primary2" /> </Button> </Tooltip> </Layout.Group> ``` ## Show/hide arrow Use the `hideArrow` prop to hide an arrow element rendered alongside the tooltip. The default is set to `false`. This can be used to help visually link the tooltip with the the content. ```jsx live <Layout.Group grow> <Tooltip content="Hide Arrow" hideArrow positionOffset={8}> <Button>Hide Arrow</Button> </Tooltip> <Tooltip content="Show Arrow"> <Button>Show Arrow</Button> </Tooltip> </Layout.Group> ``` ## Variant Use the `variant` prop to choose the color variant of the tooltip. The default is `gray`, the other option is `white`, which sets a white background. ```jsx live <Layout.Group grow> <Tooltip content="Gray background"> <Button>Gray Variant</Button> </Tooltip> <Tooltip content="White background" variant="white"> <Button>White Variant</Button> </Tooltip> </Layout.Group> ``` ## When should I use a tooltip vs a popover? Glad you asked! There are several considerations when deciding between a [Tooltip](/web/ui/tooltip) or a [Popover](/web/ui/popover): ### Purpose of content - A [Tooltip](/web/ui/tooltip) is a hint or a tip about what an interactive element does. Tooltips are meant to help clarify or provide supplementary instruction for an element on hover or upon receiving focus. They should not be used to add additional content nor should they include interactive elements such as links. Tooltips should not receive mouse or keyboard focus. Try to position tooltips so they do not overlap and cover other content on the screen. This helps keep all content readable by all users and reduces concerns regarding <ExitLink href="https://www.w3.org/WAI/WCAG21/Understanding/content-on-hover-or-focus.html">WCAG 2.1 SC 1.4.13: Content on Hover or Focus</ExitLink> - A [Popover](/web/ui/popover) should be used to provide additional content to static text, such as definitions of words, informational blurbs, or additional product details. They can receive focus and can contain links and other interactive elements. ### Size of content - Since [Tooltips](/web/ui/tooltip) are only meant to tell the purpose of an element they should be short and to the point, for example: "Click X to do X" or "User post count". - [Popovers](/web/ui/popover), on the other hand, can be much more verbose, they can include a heading, lines of text in the body, links, etc. ### Interactions - [Tooltips](/web/ui/tooltip) should only be visible on mouse hover or upon receiving focus. For this reason, if you need to be able to read the content while interacting with other parts of the page then a [Tooltip](/web/ui/tooltip) will not work. They should be dismissible using the "escape" key. They should be used on interactive elements where a mouse click or keyboard activation would otherwise trigger the elements primary function. - [Popovers](/web/ui/popover) must be triggered to appear, whether via mouse click or via keyboard navigation. They must be dismissible, whether by clicking on other parts of the page, clicking the [Popover](/web/ui/popover) target, or a specific close button/icon (depending on implementation). For this reason, you can set up a [Popover](/web/ui/popover) to allow you to interact with other elements on the page while still being able to read its content. On top of this, since [Popovers](/web/ui/popover) will remain open when mousing out of their target, you can add additional buttons or interactions within them. ### Mobile screens Tooltips only work on mouse hover (or keyboard focus). Since mobile users can't hover, the tooltip won't appear, rendering it ineffective and leading to a poor user experience where essential information might be inaccessible. Instead, we recommend using our [Popover](/web/ui/popover) component for a better mobile experience. Also, bear in mind that mobile screens are smaller, so please keep your content concise to ensure readability. ### Conclusion If you want to give a short hint or supplemental instructions for an interactive element (such as a submit button), use a [Tooltip](/web/ui/tooltip). If you want to add additional content to a static element that might include headings, body text, links, etc, and you need the content to remain open even after mousing away or the element losing focus, then use a [Popover](/web/ui/popover). It should be noted that any vital information users need to complete an action or make a decision should be displayed directly in the page text or button label, rather than a [Tooltip](/web/ui/tooltip) or a [Popover](/web/ui/popover). Critical information hidden in a [Tooltip](/web/ui/tooltip) or a [Popover](/web/ui/popover) might not be discovered by all users and could create accessibility issues. </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={Tooltip} rows={[ { name: 'content', type: 'string', description: 'Conceptual text that appears on pointer hover or keyboard focus.', }, { name: 'position', type: '"top" | "bottom" | "left" | "right" ', description: 'Sets the position of the tooltip from the trigger', }, { name: 'positionOffset', type: 'number', description: 'Sets the distance in pixels from the trigger', }, { name: 'align', type: '"start" | "center" | "end"', description: 'Sets the alignment against the trigger', }, { name: 'children', type: 'ReactNode', description: 'The children element of the tooltip', }, { name: 'asChild', type: 'boolean', description: 'Sets the component to the HTML tag or custom component of the only child.', }, { name: 'delayDuration', type: 'number', description: 'Sets the time it takes for tooltip to open', }, { name: 'hideArrow', type: 'boolean', description: 'Flag to show/hide arrow rendered alongside tooltip', }, { name: 'variant', type: '"gray" | "white"', description: 'Sets the color scheme of the tooltip', }, ]} /> ``` ```jsx render <Docs.ClassesTable of={Tooltip} rows={[ { name: 'tooltip-root', description: 'Tooltip root element', }, { name: 'tooltip-portal', description: 'Tooltip portal element', }, { name: 'tooltip-trigger', description: 'Tooltip trigger element', }, { name: 'tooltip-content', description: 'Tooltip content element', }, ]} /> ``` </Tab> <Tab label="Accessibility"> Tooltips provide contextual information about an element when that owning element receives focus or is hovered over, but are otherwise not visible on the page. While a Tooltip can be placed on any content, they are intended to be used for controls or small visual elements, such as providing additional content for icons with a brief label (or no label at all, which is not accessible!). From an accessibility and usability perspective, try to position tooltips so they do not overlap and cover other content on the screen. This helps keep all content readable by all users and reduces concerns regarding <ExitLink href="https://www.w3.org/WAI/WCAG21/Understanding/content-on-hover-or-focus.html">WCAG 2.1 SC 1.4.13: Content on Hover or Focus</ExitLink>. Instead of using tooltips and hiding important information, if you have the space, consider writing clear, succinct, always-visible descriptions such as labels and body text. Check out the <ExitLink href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/tooltip_role">Mozilla `tooltip` role</ExitLink> docs to learn more. Adheres to the <ExitLink href="https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/">Tooltip WAI-ARIA design pattern</ExitLink>. ```jsx live <Layout.Group> <Tooltip content="Contact Us"> <Button aria-label="Contact Us" rounded> <IconSymbol icon="speaker_notes" color="$primary2" /> </Button> </Tooltip> </Layout.Group> ``` ```jsx render <Docs.AccessibilityTable rows={[ { name: 'Tab', description: 'Opens/closes the tooltip without delay.', }, { name: 'Escape', description: 'If open, closes the tooltip without delay.', }, ]} /> ``` </Tab> --- id: translate category: I18n title: Translate description: Used to retrieve translated strings from the Abyss i18n object. sourceIsTS: true --- <Tab label="Overview"> ```jsx import { Translate } from '@uhg-abyss/web/ui/Translate'; ``` ## Usage The `Translate` component accepts a function with one parameter: an object with keys `t` and `i18n`. - The `t` property is a function that is used to retrieve translated strings from the i18n object and supply values to the placeholders. - The `i18n` property is the i18n object itself. The `t` function takes two arguments: ```jsx t(key: string, replacements?: object): string ``` The `key` argument corresponds to the key in the i18n object. The `replacements` argument is an object that contains the values to replace in the translated string. ## Example Let's use an example to illustrate how the `Translate` component works. The [ResultCount](/web/ui/pagination#resultcount) component displays the currently visible results and the total number of results. We can get the value of this text with the key `'ResultCount.multipleResults'`: ```jsx live-expanded () => { return ( <Translate> {({ t }) => <Text>{t('ResultCount.multipleResults')}</Text>} </Translate> ); }; ``` Notice the values in double curly braces (`{{ }}`). These are placeholder values. If we want to manually replace these, we can pass in the `replacements` object with the keys `resultFrom`, `resultTo`, and `resultsTotalCount`. ```jsx live-expanded () => { return ( <Translate> {({ t }) => ( <Text> {t('ResultCount.multipleResults', { resultFrom: 1, resultTo: 5, resultsTotalCount: 10, })} </Text> )} </Translate> ); }; ``` Note: In regular usage of Abyss components, passing these replacements in manually is unnecessary. All components will automatically replace these placeholders with the correct values. We can also use the `Translate` component to get the translated string from the `i18n` object. Note that this method does not provide a built-in way to supply values to the placeholders. ```jsx live-expanded () => { return ( <Translate> {({ i18n }) => <Text>{i18n.ResultCount.multipleResults}</Text>} </Translate> ); }; ``` ## Related links - [I18nProvider](/web/ui/i18n-provider) - [useTranslate](/web/hooks/use-translate) </Tab> <Tab label="Integration"> ```jsx render <Docs.PropsTable of={Translate} rows={[ { name: 'children', type: '() => React.ReactNode', description: 'Function used to access the i18n object and translation function', }, ]} /> ``` </Tab>