Skip to content

Commit a52aef0

Browse files
matteasonmatteason
committed
Docs for header, select, skip link
1 parent 4e8e57d commit a52aef0

File tree

9 files changed

+376
-14
lines changed

9 files changed

+376
-14
lines changed

‎README.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,15 +28,15 @@ Documentation is generated by running `npm run generate`. This generates static
2828
| Fieldset | Yes | |
2929
| File upload | Yes | |
3030
| Footer | | |
31-
| Header | | |
31+
| Header | Yes | |
3232
| Inset text | Yes | |
3333
| Notification banner | Yes | |
3434
| Pagination | | |
3535
| Panel | Yes | |
3636
| Phase banner | Yes | |
3737
| Radios | Yes | |
38-
| Select | | |
39-
| Skip link | | |
38+
| Select | Yes | |
39+
| Skip link | Yes | |
4040
| Summary list | Yes | |
4141
| Table | Yes | |
4242
| Tabs | Yes | |

‎components/GvdPageWrapper.vue

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -159,4 +159,15 @@ $gvd-button-inverted-hover-background-colour: govuk-tint($gvd-button-inverted-fo
159159
box-shadow: inset 0 0 0 2px $govuk-focus-colour;
160160
}
161161
162+
// The header and footer containers only has margin on small screens by default - we have to add some
163+
// otherwise headers and footers in code samples don't have any spacing before the logo
164+
.gvd-code-sample--rendered {
165+
.govuk-header__container.govuk-width-container,
166+
.govuk-cookie-banner__message.govuk-width-container,
167+
.govuk-footer .govuk-width-container {
168+
margin-left: 30px;
169+
margin-right: 30px;
170+
}
171+
}
172+
162173
</style>

‎content/2.components/header.md

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
---
2+
layout: component
3+
---
4+
5+
# Header
6+
7+
The GOV.UK header shows users that they are on GOV.UK and which service they are using.
8+
9+
See the [GOV.UK Design System documentation on the header](https://design-system.service.gov.uk/components/header/)
10+
for more information on when to use this component.
11+
12+
```vue-html
13+
<gv-header />
14+
```
15+
16+
## Adding a service name
17+
18+
Use the `service-name` prop or slot to include your service name in the header.
19+
20+
```vue-html
21+
<gv-header service-name="Service name" />
22+
```
23+
24+
## Adding navigation links
25+
26+
Pass a list of `GvHeaderNavigationItem`s in the `navigation` slot to include navigation links. Set the `active` prop to
27+
`true` if the link is for the current page or one of its children.
28+
29+
```vue-html
30+
<gv-header service-name="Service name">
31+
<template #navigation>
32+
<gv-header-navigation-item href="#" :active="true">
33+
Navigation item 1
34+
</gv-header-navigation-item>
35+
<gv-header-navigation-item href="#">
36+
Navigation item 2
37+
</gv-header-navigation-item>
38+
<gv-header-navigation-item href="#">
39+
Navigation item 3
40+
</gv-header-navigation-item>
41+
<gv-header-navigation-item href="#">
42+
Navigation item 4
43+
</gv-header-navigation-item>
44+
</template>
45+
</gv-header>
46+
```
47+
48+
### Using `router-link` or `nuxt-link` for navigation links
49+
50+
You can set up navigation links to use `router-link` or `nuxt-link` if needed. See
51+
[Using router-link or nuxt-link](/get-started/using-router-link-or-nuxt-link) for more details.
52+
53+
```vue
54+
<script setup lang="ts">
55+
import { NuxtLink } from '#components';
56+
</script>
57+
58+
<template>
59+
<gv-header service-name="Service name">
60+
<template #navigation>
61+
<gv-header-navigation-item :component="NuxtLink" to="/example-page" :active="true">
62+
Navigation item 1
63+
</gv-header-navigation-item>
64+
<gv-header-navigation-item :component="NuxtLink" to="/example-page">
65+
Navigation item 2
66+
</gv-header-navigation-item>
67+
<gv-header-navigation-item :component="NuxtLink" to="/example-page">
68+
Navigation item 3
69+
</gv-header-navigation-item>
70+
<gv-header-navigation-item :component="NuxtLink" to="/example-page">
71+
Navigation item 4
72+
</gv-header-navigation-item>
73+
</template>
74+
</gv-header>
75+
</template>
76+
```
77+
78+
## Customising the logo
79+
80+
Use the `logo` slot to override the default GOV.UK logo - for example, to use a departmental logo instead.
81+
82+
Using this slot overrides the `govuk-header__logo` `div` and everything inside it, so props such as `homepageUrl`
83+
and `productName` won't work. Include these elements in your slot content if you need them.
84+
85+
If your logo is white, use `fill="currentColor"` rather than `fill="#fff"` in the SVG. This will ensure the logo remains
86+
visible when printed, as the logo will automatically be changed to black. It will also ensure the logo remains visible
87+
if the user has set up custom colours in their browser or is using high contrast mode.
88+
```vue
89+
<template>
90+
<gv-header>
91+
<template #logo>
92+
<div class="govuk-header__logo app-header__logo">
93+
<a href="/" class="govuk-header__link govuk-header__link--homepage">
94+
<span class="govuk-header__logotype">
95+
<svg
96+
aria-hidden="true"
97+
focusable="false"
98+
class="govuk-header__logotype-crown"
99+
xmlns="http://www.w3.org/2000/svg"
100+
viewBox="0 0 47 30"
101+
height="30"
102+
width="47"
103+
>
104+
<polygon points="46.79769 7.68277 32.97322 11.4032 35.04362 14.9896 41.13804 13.34242 37.98907 25.09613 23.5 0 9.01093 25.09613 5.86196 13.34242 11.95638 14.9896 14.02678 11.4032 .20231 7.68277 6.18155 29.99698 6.1796 30 13.10712 30 23.5 12.00043 33.89288 30 40.8204 30 40.81845 29.99698 46.79769 7.68277" fill="currentColor"/>
105+
</svg>
106+
<span class="govuk-header__logotype-text"> GOV.UK Vue </span>
107+
</span>
108+
</a>
109+
</div>
110+
</template>
111+
</gv-header>
112+
</template>
113+
114+
<style>
115+
.app-header__logo {
116+
width: 100%;
117+
}
118+
</style>
119+
```
120+
121+
## Customising the content
122+
123+
Use the `content` slot to override the default layout of the rest of the header.
124+
125+
Using this slot overrides the `govuk-header__content` `div` and everything inside it, so props such as `serviceName`
126+
and the `navigation` slot won't work. Include these elements in your slot content if you need them.
127+
128+
::gvd-options{component="Header" :showName=true}
129+
::
130+
131+
::gvd-options{component="HeaderNavigationItem" :showName=true}
132+
::

‎content/2.components/select.md

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
layout: component
3+
---
4+
5+
# Select
6+
7+
The select component allows users to choose an option from a list.
8+
9+
See the [GOV.UK Design System documentation on selects](https://design-system.service.gov.uk/components/select/)
10+
for more information on when to use this component.
11+
12+
```vue-html
13+
<gv-select label="Sort by">
14+
<gv-select-option value="published">
15+
Recently published
16+
</gv-select-option>
17+
<gv-select-option value="updated">
18+
Recently updated
19+
</gv-select-option>
20+
<gv-select-option value="views">
21+
Most views
22+
</gv-select-option>
23+
<gv-select-option value="comments">
24+
Most comments
25+
</gv-select-option>
26+
</gv-select>
27+
```
28+
29+
## Binding with `v-model` and using events
30+
31+
The select component supports the same `v-model` binding behaviour as `<select>`.
32+
33+
Each option needs a `value`. The value of `v-model` will be set to the `value` of the selected option.
34+
35+
`value`s can be simple types, like strings or numbers, or more complex objects.
36+
37+
You can also attach event listeners and they'll be bound to the underlying `<select>`.
38+
39+
```vue
40+
<script setup lang="ts">
41+
import { ref } from 'vue'
42+
43+
const sortOptions = [
44+
{ label: 'Price, high to low', property: 'price', direction: 'descending' },
45+
{ label: 'Price, low to high', property: 'price', direction: 'ascending' },
46+
]
47+
48+
const selectedSort = ref(null)
49+
50+
function handleChange() {
51+
alert('You changed the sort value')
52+
}
53+
</script>
54+
55+
<template>
56+
<gv-select
57+
v-model="selectedSort"
58+
label="Sort by"
59+
@change="handleChange"
60+
>
61+
<gv-select-option
62+
v-for="sortOption in sortOptions"
63+
:key="sortOptions.label"
64+
:value="sortOption"
65+
>
66+
{{ sortOption.label }}
67+
</gv-select-option>
68+
</gv-select>
69+
70+
<gv-inset-text v-if="selectedSort" aria-live="polite">
71+
Sorting by {{ selectedSort.label.toLowerCase() }}
72+
</gv-inset-text>
73+
</template>
74+
```
75+
76+
## Select with hint
77+
78+
You can add a hint using the `hint` prop or slot.
79+
80+
```vue-html
81+
<gv-select
82+
label="Choose location"
83+
hint="This can be different to where you went before"
84+
>
85+
<gv-select-option value="eastmidlands">East Midlands</gv-select-option>
86+
<gv-select-option value="eastofengland">East of England</gv-select-option>
87+
<gv-select-option value="london">London</gv-select-option>
88+
<gv-select-option value="northeast">North East</gv-select-option>
89+
<gv-select-option value="northwest">North West</gv-select-option>
90+
<gv-select-option value="southeast">South East</gv-select-option>
91+
<gv-select-option value="southwest">South West</gv-select-option>
92+
<gv-select-option value="westmidlands">West Midlands</gv-select-option>
93+
<gv-select-option value="yorkshire">Yorkshire and the Humber</gv-select-option>
94+
</gv-select>
95+
```
96+
97+
## Error messages
98+
99+
Use the `error-message` prop or slot to show an error message if the user has not selected an option for a mandatory select.
100+
101+
```vue-html
102+
<gv-select
103+
label="Choose location"
104+
hint="This can be different to where you went before"
105+
error-message="Select a location"
106+
>
107+
<gv-select-option value="eastmidlands">East Midlands</gv-select-option>
108+
<gv-select-option value="eastofengland">East of England</gv-select-option>
109+
<gv-select-option value="london">London</gv-select-option>
110+
<gv-select-option value="northeast">North East</gv-select-option>
111+
<gv-select-option value="northwest">North West</gv-select-option>
112+
<gv-select-option value="southeast">South East</gv-select-option>
113+
<gv-select-option value="southwest">South West</gv-select-option>
114+
<gv-select-option value="westmidlands">West Midlands</gv-select-option>
115+
<gv-select-option value="yorkshire">Yorkshire and the Humber</gv-select-option>
116+
</gv-select>
117+
```
118+
119+
::gvd-options{component="Select" :showName=true}
120+
::
121+
122+
::gvd-options{component="SelectOption" :showName=true}
123+
::

‎content/2.components/skip-link.md

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
layout: component
3+
---
4+
5+
# Skip link
6+
7+
Use the skip link component to help keyboard-only users skip to the main content on a page.
8+
9+
See the [GOV.UK Design System documentation on the skip link](https://design-system.service.gov.uk/components/skip-link/)
10+
for more information on when to use this component.
11+
12+
```vue-html
13+
<p class="govuk-body">
14+
To view the skip link component tab to this example, or click inside this example and press tab.
15+
</p>
16+
<gv-skip-link />
17+
```
18+
19+
## Setting the skip target
20+
21+
By default, the skip link will jump to an element with the ID `content`.
22+
Use the `href` prop to override this. The skip link will jump here when activated.
23+
24+
This component does not support [custom link components](/get-started/using-router-link-or-nuxt-link), such as
25+
`router-link` or `nuxt-link`, because the link should always jump to a section on the current page.
26+
27+
```vue-html
28+
<p class="govuk-body">
29+
To view the skip link component tab to this example, or click inside this example and press tab.
30+
</p>
31+
<gv-skip-link href="#main"/>
32+
<div id="main">
33+
<p class="govuk-body">
34+
The skip link will jump here.
35+
</p>
36+
</div>
37+
```
38+
39+
## Positioning the skip link
40+
41+
The skip link should be the first component on the page, except if you're using a [cookie banner](cookie-banner). If
42+
you're using a cookie banner, the skip link should come straight after it.
43+
44+
```vue
45+
46+
<script setup lang="ts">
47+
import GvdHeader from './GvdHeader.vue'
48+
49+
function acceptCookies() {
50+
alert("You've clicked the accept button")
51+
}
52+
53+
function rejectCookies() {
54+
alert("You've clicked the reject button")
55+
}
56+
</script>
57+
58+
<template>
59+
<p class="govuk-body">
60+
To view the skip link component tab to this example, or click inside this example and press tab. The skip link will
61+
appear after you've tabbed through the cookie banner.
62+
</p>
63+
<gv-cookie-banner
64+
heading="Cookies on [name of service]"
65+
accept-button-text="Accept analytics cookies"
66+
reject-button-text="Reject analytics cookies"
67+
view-cookies-link-text="View cookies"
68+
view-cookies-link-href="#"
69+
@acceptClicked="acceptCookies"
70+
@rejectClicked="rejectCookies"
71+
>
72+
<template #cookie-information>
73+
<p class="govuk-body">We use some essential cookies to make this service work.</p>
74+
<p class="govuk-body">We’d also like to use analytics cookies so we can understand how you use the service and
75+
make improvements.</p>
76+
</template>
77+
<template #accepted>
78+
<p class="govuk-body">
79+
You’ve accepted analytics cookies. You can <a href="#" class="govuk-link">change your cookie settings</a> at any
80+
time.
81+
</p>
82+
</template>
83+
<template #rejected>
84+
<p class="govuk-body">
85+
You’ve rejected analytics cookies. You can <a href="#" class="govuk-link">change your cookie settings</a> at any
86+
time.
87+
</p>
88+
</template>
89+
</gv-cookie-banner>
90+
<gv-skip-link />
91+
<gv-header />
92+
</template>
93+
```
94+
95+
::gvd-options{component="SkipLink"}
96+
::

0 commit comments

Comments
 (0)