Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Created documentation for SkipToContentLink #2326

Merged
merged 27 commits into from
Nov 12, 2024
Merged
Show file tree
Hide file tree
Changes from 20 commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
30562ff
created doc for skip to main content link
smmr-dn Nov 1, 2024
a6b050b
added example
smmr-dn Nov 4, 2024
488a7d3
attempted to fix a11y error
smmr-dn Nov 5, 2024
2a3b768
Merge branch 'main' into uyen/skip-content-doc
smmr-dn Nov 5, 2024
4df97df
revert example changes
smmr-dn Nov 5, 2024
89d4bbb
Merge branch 'uyen/skip-content-doc' of https://github.com/iTwin/iTwi…
smmr-dn Nov 5, 2024
602b8d8
revert example changes
smmr-dn Nov 5, 2024
c054d95
modified examples
smmr-dn Nov 6, 2024
a800e82
description wording
smmr-dn Nov 6, 2024
13d7985
Merge branch 'main' into uyen/skip-content-doc
smmr-dn Nov 6, 2024
c5f6065
changed examples and wording
smmr-dn Nov 7, 2024
fa06deb
Merge branch 'uyen/skip-content-doc' of https://github.com/iTwin/iTwi…
smmr-dn Nov 7, 2024
aa63244
typo
smmr-dn Nov 7, 2024
ccf8a97
more wording
smmr-dn Nov 7, 2024
2e9164e
more wording
smmr-dn Nov 7, 2024
0105931
more explanation in intro
smmr-dn Nov 7, 2024
da92a8c
more explanation in intro
smmr-dn Nov 7, 2024
e05ab6b
removed redundancies
smmr-dn Nov 7, 2024
3428273
Merge branch 'main' into uyen/skip-content-doc
smmr-dn Nov 7, 2024
ef63dc8
Merge branch 'main' into uyen/skip-content-doc
smmr-dn Nov 11, 2024
4a13cc0
make skip link appear from the top
smmr-dn Nov 11, 2024
fc47ca0
Merge branch 'uyen/skip-content-doc' of https://github.com/iTwin/iTwi…
smmr-dn Nov 11, 2024
685c835
Merge branch 'main' into uyen/skip-content-doc
smmr-dn Nov 12, 2024
07c4193
modified demo
smmr-dn Nov 12, 2024
7d3ae03
Merge branch 'uyen/skip-content-doc' of https://github.com/iTwin/iTwi…
smmr-dn Nov 12, 2024
4dc7f2b
renamed id
smmr-dn Nov 12, 2024
693f526
added css comment and used normal button and kbd
smmr-dn Nov 12, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 53 additions & 0 deletions apps/website/src/content/docs/skiptocontentlink.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
---
title: SkipToContentLink
description: A skip-to-content link helps keyboard users quickly navigate to the main content.
thumbnail: #TODO
---

<p>{frontmatter.description}</p>

In some applications, numerous navigation links and other focusable elements can require a lot of keyboard presses before users reach their desired content. What is more, if users tab into a link that leads to another page with the same structure, they must tab through the same list of non-essential links again.
mayank99 marked this conversation as resolved.
Show resolved Hide resolved

While this may not be an issue for sighted or mouse users, it can be cumbersome for those who rely on keyboard navigation. Therefore, a skip link is crucial to improve accessibility and streamline navigation, designed for screen-reader and keyboard users.
mayank99 marked this conversation as resolved.
Show resolved Hide resolved

```jsx
<SkipToContentLink href='#main-content-id' />
```
mayank99 marked this conversation as resolved.
Show resolved Hide resolved

## Usage

The `SkipToContentLink` component setup requires two elements:

- The target element to skip to.
- The link pointing to that target element.

The `href` prop can be used to direct focus to the target element. This prop must be set to the `id` of the main content section, including the `"#"` prefix.
mayank99 marked this conversation as resolved.
Show resolved Hide resolved

```jsx {5}
mayank99 marked this conversation as resolved.
Show resolved Hide resolved
<div className='App'>
<SkipToContentLink href='#main-content-id' />
{/* Other elements such as header, navigation, etc. */}

<div id='main-content-id'>{/* Some main content that will be skipped to */}</div>
mayank99 marked this conversation as resolved.
Show resolved Hide resolved
</div>
```

As the skip link is visually hidden from view until focused, users typically access the link by pressing `Tab` at the start of the page. The skip link component should appear on top of the page to make sure it is one of the first items the screen readers get to and that keyboard users are able to navigate to using the keyboard.
mayank99 marked this conversation as resolved.
Show resolved Hide resolved

<LiveExample src='SkipToContentLink.main.jsx' truncate={true}>
<AllExamples.SkipToContentLinkMainExample client:load />
</LiveExample>

### Custom Text

As the link is designed for screen reader users, localization is crucial for making the application accessible and understandable. The skip link component accepts custom text through its `children` prop, allowing end users to provide a localized message.

If no custom text is provided, the default text displayed is "Skip to main content". This flexibility helps create a more inclusive and user-friendly experience for a global audience.
mayank99 marked this conversation as resolved.
Show resolved Hide resolved

<LiveExample src='SkipToContentLink.customText.jsx' truncate={true}>
<AllExamples.SkipToContentLinkCustomTextExample client:load />
</LiveExample>

## Props

<PropsTable path='@itwin/itwinui-react/esm/core/SkipToContentLink/SkipToContentLink.d.ts' />
18 changes: 18 additions & 0 deletions examples/SkipToContentLink.customText.jsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
/*---------------------------------------------------------------------------------------------
* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
* See LICENSE.md in the project root for license terms and full copyright notice.
*--------------------------------------------------------------------------------------------*/
import { Kbd, SkipToContentLink } from '@itwin/itwinui-react';

export default () => {
return (
<>
<SkipToContentLink href='#main-content'>
Skip main navigation
</SkipToContentLink>
<div id='main-content'>
To view the skip link, click inside this box then press <Kbd>Tab</Kbd>.
</div>
</>
);
};
16 changes: 16 additions & 0 deletions examples/SkipToContentLink.main.jsx
mayank99 marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
/*---------------------------------------------------------------------------------------------
* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
* See LICENSE.md in the project root for license terms and full copyright notice.
*--------------------------------------------------------------------------------------------*/
import { Kbd, SkipToContentLink } from '@itwin/itwinui-react';

export default () => {
return (
<>
<SkipToContentLink href='#main-content' />
<div id='main-content'>
To view the skip link, click inside this box then press <Kbd>Tab</Kbd>.
</div>
</>
);
};
14 changes: 14 additions & 0 deletions examples/index.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -1074,6 +1074,20 @@ export { SideNavigationSubmenuExample };

// ----------------------------------------------------------------------------

import { default as SkipToContentLinkMainExampleRaw } from './SkipToContentLink.main';
const SkipToContentLinkMainExample = withThemeProvider(
SkipToContentLinkMainExampleRaw,
);
export { SkipToContentLinkMainExample };

import { default as SkipToContentLinkCustomTextExampleRaw } from './SkipToContentLink.customText';
const SkipToContentLinkCustomTextExample = withThemeProvider(
SkipToContentLinkCustomTextExampleRaw,
);
export { SkipToContentLinkCustomTextExample };

// ----------------------------------------------------------------------------

import { default as SliderMainExampleRaw } from './Slider.main';
const SliderMainExample = withThemeProvider(SliderMainExampleRaw);
export { SliderMainExample };
Expand Down
Loading