USWDS - Table: Add sticky headers #5420

amyleadem · 2023-08-02T20:49:17Z

Summary

New table variant. Created the .usa-table--sticky-header variant to allow sticky positioning on table headers.

Caution

Sticky headers are not compatible with the scrollable and stacked table variants.

Thanks to @etanb for originating this work in PR #5074.

Breaking change

This is not a breaking change.

Related issue

Closes #5077

Related pull requests

Changelog and documentation PR

Preview link

Problem statement

For very long tables, it can be difficult to remember the associated header content. Creating the option to have table headers stick to the top of the page as the user scrolls would help keep tabular data in context.

Solution

This change creates a .usa-table--sticky-header variant that gives the table header sticky positioning.

Note
At this time, sticky headers are not compatible with the scrollable and stacked table variants. For the scrollable variant, this incompatibility is related to a known issue (on W3C CSS repo) with sticky positioning and scrolling overflow. If we want to pursue a sticky header that is compatible with scrollable tables, I recommend we open a separate issue because it will require a decent lift to find a workaround.

New variant

Variant name	Description
`.usa-table--sticky-header`	Allows the table header element to stick to the top of the page as the user scrolls. Preferred for long tables with many rows. This variant is not compatible with the scrollable and stacked table variants.

New settings

Setting name	Description
`$theme-table-background-color`	Defines the table background color. A value of `default` uses the body background color.
`$theme-table-sticky-top-offset`	Defines the top offset for sticky headers.

Testing and review

Confirm that sticky positioning works with the default, borderless, striped, and sortable table variants.
Test on a variety of browsers
Confirm that sticky headers are compatible with multiple header rows
Confirm that the new settings work as expected
Confirm no visual regressions

To test in Storybook:

In a variety of browsers, open each table variant story from the list of preview links
In each story, turn on the sticky header control
Confirm that the table header sticks to the top of the page when you scroll down

Note
Sticky headers will not stick in scrollable and stacked variants. If the header is not sticking, confirm that the scrollable control is turned off.
Turn on the control for multiple header rows
Confirm that both header rows stick to the top of the page when you scroll down and confirm that there are no visual irregularities (like table content showing behind the header on scroll)

Add sample styles to show what would be required for border-collapse: separate

…ky-table-header

- Done to improve consistency in control presentation

…ky-table-header

amyleadem

@mejiaj I believe I have addressed all your comments related to USWDS code. I am going to look into the guidance in USWDS-Site - Changelog: add entry and doc updates for sticky table headers to make sure it addresses this comment. Let me know if you need anything else.

packages/usa-table/src/usa-table.stories.js

amyleadem · 2024-01-10T23:16:28Z

packages/usa-table/src/usa-table.twig

+{% if stickyHeader %}
+  {% set bodyLoopCount = 0..6 %}
+{% else %}
+  {% set bodyLoopCount = 0..0 %}
+{% endif %}


Updated in 02034a7

packages/usa-table/src/usa-table.twig

mejiaj

Thanks @amyleadem, two more minor comments. One for improving clarity in settings and another for making the template class easier to update.

packages/usa-table/src/usa-table--sortable/usa-table--sortable.twig

mejiaj · 2024-01-19T20:16:27Z

packages/uswds-core/src/styles/settings/_settings-components.scss

@@ -213,6 +214,7 @@ $theme-table-sorted-header-background-color: "accent-cool-light" !default;
 $theme-table-sorted-background-color: "accent-cool-lighter" !default;
 $theme-table-sorted-stripe-background-color: "blue-cool-10v" !default;
 $theme-table-sorted-icon-color: default !default;
+$theme-table-sticky-top-offset: -1px !default;


Small concern here is this is similar to the current hero setting where it's not very flexible or re-usable.

Not a blocker for this work.

Yeah, the setting is fairly limited, but I am not sure if there is a way around it. I would imagine a lot of projects will need to write some custom style rules for the top offset.

@amyleadem does this setting accept units too or only pixels? Do we have any guidance for this?

amyleadem · 2024-01-23T22:31:10Z

@mejiaj I believe I've addressed your concerns. Let me know if you have any questions.

mejiaj

Question on new offset setting. Code looks good, thank you.

thisisdano

NICE

etanb and others added 16 commits December 20, 2022 11:58

add the ability to sticky the header of the table component

9a8a13a

prettier

567876c

Merge branch 'develop' into eb-sticky-table-header

93269e5

fixes to implementation

630eadc

Add sticky header control

4c9a177

Override position:relative on sortable sticky th cells

ab1e642

Remove stickyheader control

455296b

Add sortable JSON file

db6c5f7

Add demo for multi-row headers

3b03d79

Add sample styles to show what would be required for border-collapse: separate

Add multipleHeaderRows control for testing

8dae8db

Remove background color and extra borders from sticky table thead

a060c6a

Disable multipleHeaderRows for sortable tables

37d56a8

Remove text-right from table header

63f925b

Merge branch 'develop' of https://github.com/uswds/uswds into al-stic…

08024a6

…ky-table-header

Run prettier

81c43dd

Add settings for table background color and sticky table top offset

40dac7c

amyleadem mentioned this pull request Aug 2, 2023

USWDS - Table component: add ability to make headers sticky as user scrolls #5074

Closed

Amy Leadem added 10 commits August 2, 2023 14:46

Move stickyheader from json to a storybook control

a477cd0

- Done to improve consistency in control presentation

Remove stickyheader check on scrollable variant

ab585ae

Format code

da2a9e7

Move scrollable setting from json to storybook

6bd2f54

Let $theme-table-background-color accept default

fd01eb4

Run prettier

54debdc

Fix default for $theme-table-background-color

121762b

Clean up multiple header rows code

65c03b6

Add scrollable conditional to sortable twig

feaaecd

Create loops for header and body rows

ba30313

amyleadem mentioned this pull request Aug 4, 2023

USWDS-Site - Changelog: add entry and doc updates for sticky table headers [USWDS#5420] uswds/uswds-site#2229

Merged

Amy Leadem added 2 commits August 4, 2023 10:18

Remove background color on table button default

17b90e5

Merge branch 'develop' of https://github.com/uswds/uswds into al-stic…

d02ebdc

…ky-table-header

amyleadem added 4 commits January 10, 2024 16:15

Use underscores for twig variables

02034a7

Add note to sticky header + mult header controls

58d0a6a

Add underscore to stickheader json + twig

c4d13e7

Remove "Note:" from scrollable control

b79fdf2

amyleadem commented Jan 11, 2024

View reviewed changes

amyleadem requested a review from mejiaj January 18, 2024 17:57

mejiaj suggested changes Jan 19, 2024

View reviewed changes

amyleadem added 2 commits January 23, 2024 15:10

Create test: multiple header rows + sticky header

1e447af

Assign sticky_header_class on sortable twig

cae00e5

Run prettier

b10cae4

amyleadem requested a review from mejiaj January 23, 2024 22:32

mahoneycm mentioned this pull request Feb 1, 2024

USWDS-Site: Documentation updates for release 3.8.0 uswds/uswds-site#2477

Closed

5 tasks

mejiaj approved these changes Feb 1, 2024

View reviewed changes

mejiaj requested review from thisisdano and removed request for amycole501 and alex-hull February 1, 2024 20:10

amyleadem mentioned this pull request Feb 23, 2024

USWDS - Table: Simplify scrollable table example for site #5783

Merged

3 tasks

thisisdano approved these changes Feb 26, 2024

View reviewed changes

thisisdano merged commit 090a9ee into develop Feb 26, 2024

thisisdano deleted the al-sticky-table-header branch February 26, 2024 23:36

This was referenced Feb 28, 2024

USWDS-Site: Documentation updates for release 3.8.0 uswds/uswds-site#2509

Merged

USWDS: Release 3.8.0 tasks #5797

Closed

thisisdano mentioned this pull request Mar 11, 2024

USWDS 3.8.0 #5812

Merged

SherfeyInv mentioned this pull request Jun 7, 2024

[Snyk] Upgrade @uswds/uswds from 3.7.1 to 3.8.0 SherfeyInv/digitalgov.gov#4

Closed

lane-formio mentioned this pull request Jun 22, 2024

[Snyk] Upgrade @uswds/uswds from 3.8.0 to 3.8.1 formio/uswds-viewer#21

Closed

mejiaj mentioned this pull request Jul 8, 2024

General updates applying BEM and USWDS structures Bixal/bixaluswds#19

Merged

10 tasks

sennhann29 mentioned this pull request Jul 26, 2024

[Snyk] Upgrade @uswds/uswds from 3.4.1 to 3.8.1 sennhann29/digitalgov.gov#4

Open

lane-formio mentioned this pull request Aug 31, 2024

[Snyk] Upgrade @uswds/uswds from 3.8.0 to 3.8.2 formio/uswds-viewer#25

Merged

FuhuXia mentioned this pull request Sep 26, 2024

[Snyk] Upgrade @uswds/uswds from 3.8.0 to 3.8.2 GSA/datagov-harvester#101

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

USWDS - Table: Add sticky headers #5420

USWDS - Table: Add sticky headers #5420

Uh oh!

amyleadem commented Aug 2, 2023 •

edited by mejiaj

Loading

Uh oh!

amyleadem left a comment

Uh oh!

Uh oh!

amyleadem Jan 10, 2024

Uh oh!

Uh oh!

mejiaj left a comment

Uh oh!

Uh oh!

mejiaj Jan 19, 2024

Uh oh!

amyleadem Jan 23, 2024

Uh oh!

mejiaj Feb 1, 2024

Uh oh!

amyleadem commented Jan 23, 2024

Uh oh!

mejiaj left a comment •

edited

Loading

Uh oh!

thisisdano left a comment

Uh oh!

Uh oh!

USWDS - Table: Add sticky headers #5420

USWDS - Table: Add sticky headers #5420

Uh oh!

Conversation

amyleadem commented Aug 2, 2023 • edited by mejiaj Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Breaking change

Related issue

Related pull requests

Preview link

Problem statement

Solution

New variant

New settings

Testing and review

Uh oh!

amyleadem left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

amyleadem Jan 10, 2024

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mejiaj left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mejiaj Jan 19, 2024

Choose a reason for hiding this comment

Uh oh!

amyleadem Jan 23, 2024

Choose a reason for hiding this comment

Uh oh!

mejiaj Feb 1, 2024

Choose a reason for hiding this comment

Uh oh!

amyleadem commented Jan 23, 2024

Uh oh!

mejiaj left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thisisdano left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

amyleadem commented Aug 2, 2023 •

edited by mejiaj

Loading

mejiaj left a comment •

edited

Loading