govuk-elements-marko
v5.2.8
Published
GOV.UK elements as Marko components.
Downloads
36
Readme
A set of Marko components implementing GOV.UK elements.
Installing
npm install govuk-elements-marko --save
Note: you will need to have the GOV.UK elements sass compiling in your service in order for the components to be styled correctly.
npm install govuk-elements-sass --save
Components
<gov-input/>
The <gov-input/>
tag will render a standard GOV.UK input and label pair.
The input id will be set as 'input' followed by a dash and the input's name attribute.
For example:
<gov-input name='full-name' label='Full name'/>
Will produce the following markup:
<div class="form-group">
<label for="input-full-name">
<span class="form-label">Full name</span>
</label>
<input class="form-control" type="text" id="input-full-name" name="full-name"
autocomplete="off">
</div>
Attributes
- name - sets input name attribute (required)
- label - sets label text (required)
- hint - sets label hint text
- group-classes - appends further classes
<div class="form-group">
- input-classes - appends further classes
<input class="form-control">
; eg.form-control-1-4
for quarter width. - id - override generated input id attribute
- error - sets error message text
- value - sets input value attribute
- maxlength - sets input maxlength attribute
- hide-label - adds visually-hidden to the input label (true/false)
<gov-date-input/>
<gov-date-input\>
will generate the mark up for the GOV.UK date input
pattern. It
supports multiple name attribute formats to accommodate on your node
body parser set up. It does not currently support separate error messages and
highlighting per input.
The input ids are set as the input's name attribute followed by a dash and
either 'day', 'month' or 'year', eg. birth-day
, birth-month
, etc. The
format can be changed using the 'suffix' attribute, eg. suffix="camel"
will
produce name="birthDay"
while suffix="object"
will give name="birth[day]"
.
Kebab case is default, name="birth-day"
.
Note: Day, month and year labels are currently hardcoded! Welsh is supported using the 'lang' attribute. It is also detected from the 'language' property of the express request object.
Example:
<gov-date-input name="date-of-birth" legend="What is your date of birth?"
hint="For example, 31 3 1980"/>
Will produce the following markup:
<div class="form-group">
<fieldset>
<legend>
<span class="form-label-bold">What is your date of birth?</span>
<span id="date-of-birth-hint" class="form-hint">For example, 31 3 1980</span>
</legend>
<div class="form-date">
<div class="form-group form-group-day">
<label for="input-date-of-birth-day" class="form-label">Day</label>
<input aria-describedby="date-of-birth-hint" class="form-control"
id="input-date-of-birth-day" name="date-of-birth-day"
pattern="[0-9]*" min="0" max="31" type="number"/>
</div>
<div class="form-group form-group-month">
<label for="input-date-of-birth-month" class="form-label">Month</label>
<input class="form-control" id="input-date-of-birth-month"
name="date-of-birth-month" pattern="[0-9]*" min="0"
max="12" type="number"/>
</div>
<div class="form-group form-group-year">
<label for="input-date-of-birth-year" class="form-label">Year</label>
<input class="form-control" id="input-date-of-birth-year"
name="date-of-birth-year" pattern="[0-9]*" min="0"
type="number"/>
</div>
</div>
</fieldset>
</div>
Attributes
- name - sets input name attribute (required)
- legend - sets legend text (required)
- hint - sets legend hint text
- group-classes - appends further classes
<div class="form-group">
- id - overrides the name part of the input ids
- error - sets error message text
- value - set input values using object, eg.
value={day: '1', month: '2', year: '2017'}
- value-day - set value attribute day input
- value-month - set value attribute month input
- value-year - set value attribute year input
- maxyear - set max attribute on year input
- suffix - set input id generation suffix (explained above)
- lang - setting to 'cy' uses Welsh labels, anything else defaults to English
<gov-checkbox/>
Use <gov-checkbox/>
to generate a GOV.UK checkbox!
The input id will be set as 'checkbox' followed by a dash and the input's name
attribute, eg. checkbox-cat
.
Example:
<gov-checkbox label="I have a cat" name="cat" value="true"/>
Will produce the following mark up:
<div class="multiple-choice">
<input id="checkbox-cat" name="cat" value="true" type="checkbox"/>
<label for="checkbox-cat">I have a cat</label>
</div>
Attributes
- <gov-checkbox/>
- name - sets name attribute value, overrides group name if it exists
- value - sets input value attribute (required)
- label - sets label text (required)
- hint - sets label hint text
- reveal - sets
data-target
attribute for conditionally revealing content.
<gov-checkboxes/>
Use <gov-checkboxes/>
to generate a GOV.UK checkbox group!
The input id will be set as 'checkbox' followed by a dash, the input's name
attribute, another dash and the index of the input, eg. checkbox-cats-0
.
If you are implementing a one question per page pattern and wish to hide the legend, you can set the 'hide-legend' to true. This will add a 'visually-hidden' class.
Example:
<gov-checkboxes legend="Which types of waste do you transport regularly?"
name="waste-types" body-text="Select all that apply">
<@checkbox value="waste-animal" label="Waste from animal carcasses"/>
<@checkbox value="waste-mines" label="Waste from mines or quarries"/>
<@checkbox value="waste-farm" label="Farm or agricultural waste"/>
</gov-checkboxes>
Will produce the following mark up:
<div class="form-group">
<fieldset>
<legend>
<span class="form-label-bold">
Which types of waste do you transport regularly?
</span>
<span class="body-text">
Select all that apply
</span>
</legend>
<div class="multiple-choice">
<input id="checkbox-waste-types-0" name="waste-types" value="waste-animal"
type="checkbox"/>
<label for="checkbox-waste-types-0">Waste from animal carcasses</label>
</div>
<div class="multiple-choice">
<input id="checkbox-waste-types-1" name="waste-types" value="waste-mines"
type="checkbox"/>
<label for="checkbox-waste-types-1">Waste from mines or quarries</label>
</div>
<div class="multiple-choice">
<input id="checkbox-waste-types-2" name="waste-types" value="waste-farm"
type="checkbox"/>
<label for="checkbox-waste-types-2">Farm or agricultural waste</label>
</div>
</fieldset>
</div>
Attributes
- <gov-checkboxes/>
- name - sets input name attribute for all inputs
- legend - sets legend text (required)
- hide-legend - boolean, adds visually-hidden class to legend if
true
- hint - sets legend hint text
- body-text - sets legend body text
- error - sets error message text
- values - array of values, checkboxes with matching values will be rendered checked
- <@checkbox/>
- name - sets name attribute value, overrides group name if it exists
- value - sets input value attribute (required)
- label - sets label text (required)
- checked - boolean, checkes checkbox. Overrides matching values from <gov-checkboxes/> values attribute if it exists
- hint - sets label hint text
- reveal - sets
data-target
attribute for conditionally revealing content.
<gov-radios/>
Use <gov-radios/>
to generate a GOV.UK radio button group!
2 radios will be rendered side-by-side, 3 or more radios will be displayed
vertically. Layout can be forced by setting the 'layout' attribute to inline
for side-by-side or stacked
to display vertically.
The input id will be set as 'radio' followed by a dash, the input's name
attribute, another dash and the index of the input, eg. radio-cats-0
.
If you are implementing a one question per page pattern and wish to hide the legend you can set the 'hide-legend' to true. This will add a 'visually-hidden' class.
Example:
<gov-radios legend="Do you already have a personal user account?" name="account">
<@radio value="yes" label="Yes"/>
<@radio value="no" label="No"/>
</gov-radios>
Will produce the following mark up:
<div class="form-group">
<fieldset class="inline">
<legend>
<span class="form-label-bold">
Do you already have a personal user account?
</span>
</legend>
<div class="multiple-choice">
<input id="radio-account-0" name="account" value="yes" type="radio"/>
<label for="radio-account-0">Yes</label>
</div>
<div class="multiple-choice">
<input id="radio-account-1" name="account" value="no" type="radio"/>
<label for="radio-account-1">No</label>
</div>
</fieldset>
</div>
Attributes
- <gov-radios/>
- name - sets input name attribute for all inputs (required)
- legend - sets legend text (required)
- hide-legend - boolean, adds visually-hidden class to legend if
true
- hint - sets legend hint text
- error - sets error message text
- value - checks the radio which the matching value attribute
- layout -
stacked
forces radios to display vertically,inline
forces horizontal layout. Inline is default for less than 3 radios, stacked for 3 or more.
- <@radio/>
- value - sets input value attribute (required)
- label - sets label text (required)
- hint - sets label hint text
- reveal - sets
data-target
attribute for conditionally revealing content.
<gov-textarea/>
The <gov-textarea/>
tag will render a textarea and label pair.
The input id will be set as 'textarea' followed by a dash and the textarea's name attribute.
Example:
<gov-textarea name='what-wrong' label='What went wrong'/>
Will produce the following markup:
<div class="form-group">
<label for="textarea-what-wrong">
<span class="form-label">What went wrong</span>
</label>
<textarea class="form-control" id="textarea-what-wrong" rows="8"
name="what-wrong"/>
</div>
Attributes
- name - sets textarea name attribute (required)
- label - sets label text (required)
- hint - sets label hint text
- id - override generated textarea id attribute
- error - sets error message text
- value - sets input value attribute
- maxlength - textarea textarea maxlength attribute
- rows - sets textarea rows attribute
<gov-error-summary/>
<gov-error-summary/>
can be used to display a GOV.UK Elements error summary
section at the top of your page, listing form validation errors. The list will
contain anchor links pointing the error-message ids generated by the
<gov-input>
component.
It takes a heading, an optional summary and object of error messages. The error message object should contain keys matching the name attribute of an input, with the value as the appropriate error message.
If no errors object is passed, or errors is set to something non-truthy, the error summary section will not be rendered.
Example:
<gov-error-summary heading="There's a problem" summary="Fix the following"
errors={'full-name': 'You must provide a name.'}/>
Will produce the following markup:
<div role="alert" aria-labelledby="error-summary-heading" tabindex="-1"
class="error-summary">
<h2 id="error-summary-heading" class="heading-medium error-summary-heading">
There's a problem
</h2>
<p>Fix the following</p>
<ul class="error-summary-list">
<li>
<a href="#error-message-full-name">You must provide a name.</a>
</li>
</ul>
</div>
Attributes
- errors - errors object, keys match input names, associated values the error messages
- heading - sets heading text
- summary - sets summary text
<gov-prog-disclosure/>
This tag will create an summary/details tag pair following the GOV.UK progressive disclosure pattern.
Example:
<gov-prog-disclosure summary="Help with nationality">
<p>
If you’re not sure about your nationality, try to find out from an official
document like a passport or national ID card.
</p>
<p>
We need to know your nationality so we can work out which elections you’re
entitled to vote in. If you can’t provide your nationality, you’ll have to
send copies of identity documents through the post.
</p>
</gov-prog-disclosure>
Will produce the following markup:
<details>
<summary>
<span class="summary">Help with nationality</span>
</summary>
<div class="panel panel-border-narrow">
<p>
If you’re not sure about your nationality, try to find out from an
official document like a passport or national ID card.
</p>
<p>
We need to know your nationality so we can work out which elections you’re
entitled to vote in. If you can’t provide your nationality, you’ll have to
send copies of identity documents through the post.
</p>
</div>
</details>
Attributes
- summary - sets summary text
<gov-legal/>
<gov-legal/>
can be used for displaying legal text in bold with a warning
icon.
Note: Visually hidden warning text is hardcoded. In English by default, can
be set to Welsh by setting the 'lang' attribute to cy
.
Example:
<gov-legal content="You can be fined up to £5,000 if you don’t register."/>
Will produce:
<p class="notice text">
<i class="icon icon-important">
<span class="visuallyhidden">Warning</span>
</i>
<strong class="bold-small">
You can be fined up to £5,000 if you don’t register.
</strong>
</p>
Attributes
- content - sets content for the legal message
- lang - specifies the language for the visually hidden warning message,
lang="cy"
sets to Welsh, anything else defaults to English
<gov-phase-banner/>
This tag will generate a GOV.UK phase banner. Setting the value of the phase
attribute changes the text in the phase tag, defaults to BETA.
Example:
<gov-phase-banner phase="alpha">
This is a new service – your <a href="/feedback">feedback</a> will help us to
improve it.
</gov-phase-banner>
Will produce:
<div class="phase-banner">
<p>
<strong class="phase-tag">ALPHA</strong>
<span>This is a new service – your <a href="/feedback">feedback</a> will
help us to improve it.</span>
</p>
</div>
Attributes
- phase - sets content phase tag, defaults to beta.