Docs style guide

This page is a style guide for all elements/components within the dev docs.

All Headings from H2 to H6

Here you can find a selection of all the headers to use from H2 to H6

Heading 2

Heading 3

Heading 4

Heading 5
Heading 6

Here is an example of the headers with the added class="border-left"

Heading 3

Heading 4

Heading 5
Heading 6

Paragraph text, lists and anchor tags

Paragraph text - Lorem ipsum dolor sit amet consectetur, adipisicing elit. Non fugit quisquam libero dolores excepturi commodi quibusdam voluptate soluta quis dolorum tempore dicta at eos, maxime accusamus porro illum corrupti neque.

  • Lorem ipsum, dolor sit amet consectetur adipisicing elit. Dolorum, minus!
  • Lorem ipsum dolor sit amet. Style guide
  • Lorem ipsum dolor sit amet consectetur adipisicing elit. Id, expedita ratione! Nisi quam quia iste nam nulla maiores dicta neque quae hic. Amet ullam ea officiis dignissimos inventore voluptates animi!
    • This is a nested list
    • Lorem, ipsum dolor sit amet consectetur adipisicing elit. Esse, deleniti.
    • Lorem ipsum dolor sit amet consectetur adipisicing elit. Harum atque dolorem sapiente ad obcaecati quod!

Lorem ipsum dolor sit amet consectetur, adipisicing elit. Non fugit quisquam libero dolores excepturi commodi quibusdam voluptate soluta quis dolorum tempore dicta at eos, maxime accusamus porro illum corrupti neque.

Code examples

Code examples come in a few flavours

Inline Code

A pragraph with a code example within it... Madness!

GET https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/address/uk/nr14%207pz?format=json&lines=2

A code block

If you wish to show just a single block of code...

[
	{
		"addressline1": "Department of Communications, Climate Action and Environment",
		"addressline2": "29-31 Adelaide Road",
		"summaryline": "Department of Communications, Climate Action and Environment, 29-31 Adelaide Road, Dublin 2, D02 X285",
		"organisation": "Department of Communications, Climate Action and Environment",
		"number": "29-31",
		"premise": "29-31",
		"street": "Adelaide Road",
		"posttown": "Dublin 2",
		"county": "Co. Dublin",
		"postcode": "D02 X285",
		"latitude": "53.332067",
		"longitude": "-6.255492"
	}
]

A code block with tabs

If you wish to show a full working example with various file types...

class PostcoderAddress{
  
  constructor(config) {
    this.config = config
    this.init()
  }

  init = () => {

    this.endpoint = 'https://ws.postcoder.com/pcw/' + this.config.apikey + '/address/'
    this.addresses = {}

    this.searchbutton = document.querySelector(this.config.searchbutton)
    this.searchterminput = document.querySelector(this.config.searchterm)

    //hide the no result message
    this.noresultmessage = document.querySelector(this.config.noresultmessage)
    this.noresultmessage.style.display = 'none'

    // create an empty select and place it hidden in the page
    this.select = document.createElement('select')
    this.select.style.display = 'none'
    document.querySelector(this.config.addressselectioncontainer).appendChild(this.select)

    // create and append the top 'select an address' option.
    let option = document.createElement('option')
    option.text = 'Select an address'
    this.select.appendChild(option)

    // add select change event listener to the dropdown
    this.select.addEventListener('change', this.handleSelectChange )

    // add click event listener to the search button, to call the search function
    this.searchbutton.addEventListener('click', this.search)

    // add 'enter' event listener to the search input, to call the search function
    this.searchterminput.addEventListener('keyup', event =>{
      if (event.keyCode === 13) {
        event.preventDefault()
        this.search()
      }
    })

    // determine the number of addresslines required
    this.addresslines = 0
    for (let i = 1; i <= 4; i++) {
      if( this.config['addressline'+i] !== ''){
        this.addresslines ++
      }
    }    

  }

  handleSelectChange = event => {

      // check to see if this selection was to load the next page of results
      if( this.select.value.charAt(0) === 'p'){
      
        // search the next page of results
        let page = this.select.value.substring(1)
        this.search(event, page)

      }else{   

        this.selectAddress( this.select.value )

      }     
  }

  search = (event, page = 0) => {

    let searchterm = encodeURIComponent(this.searchterminput.value)

    //hide the no result message
    this.noresultmessage.style.display = 'none'

    // hide the select
    this.select.style.display = 'none'

    //determine the country
    if(typeof this.config.countrycode !== 'undefined' && this.config.countrycode !== ''){
      // defined in config
      var country = this.config.countrycode
    }else{
      // get from dropdown
      var country = document.querySelector(this.config.country).value
    }

    // if page 0, remove any previous options
    if(page === 0){
      while (this.select.options.length > 1) {                
        this.select.remove(1)
      }
    }else{
      // remove the bottom 'next page' option
      this.select.remove(this.select.options.length - 1)
    }

    // fetch the json formatted result from Postcoder and pass it to processResult
    fetch(this.endpoint + country + '/' + searchterm + '?lines='+this.addresslines + '&exclude=organisation,country&page=' + page)
      .then( response => {
        if (!response.ok) { 
          throw response 
        }
        return response.json()
      })
      .then( json => {
        this.processResult(json)
      })
      .catch( err => {

        if(typeof err.text === 'function'){
          err.text().then( errorMessage => {
            console.log('Postcoder request error ' + err.status + ' : ' + errorMessage)
          })
        }else{
          console.log(err)
        }
    })
  }

  processResult = addresses =>{

    this.addresses = addresses

    //if zero results, ask for manual address entry
    if( addresses.length === 0 ){
      
      //show the no result message
      this.noresultmessage.style.display = 'block'

    }
    // if one result, populate the form
    else if(addresses.length === 1){

      this.selectAddress(0)

    }
    // multiple addresses, show drop down to select from
    else{

      // create and append the address options, using the summaryline of the returned addresses
      for (let i = 0; i < addresses.length; i++) {
        let option = document.createElement('option')
        option.value = i
        option.text = addresses[i].summaryline
        this.select.appendChild(option)
      }

      // if there are morevalues, add paging
      if(this.addresses[this.addresses.length - 1]['morevalues'] === 'true'){

        // add a 'load next page' option
        let option = document.createElement('option')
        option.value = 'p' + this.addresses[this.addresses.length - 1]['nextpage']

        // last address contains total number of results, show the user how many are remaining
        let remainingresults = this.addresses[this.addresses.length - 1]['totalresults'] - this.select.options.length + 1

        option.text = 'Load more results, ' + remainingresults + ' of ' + this.addresses[this.addresses.length - 1]['totalresults'] + ' remaining'
        this.select.appendChild(option)

      }
      
      // ensure the select is visible
      this.select.style.display = 'block'

    }
  }

  selectAddress = i =>{

    // get the selected address
    let address = this.addresses[i]

    let fields = ['organisation','addressline1','addressline2','addressline3','addressline4','posttown','county','postcode']

    //populate the address form  
    for (let i = 0; i < fields.length; i++) {
      let field_selector = this.config[fields[i]]
      if(typeof field_selector !== 'undefined' && field_selector !== ''){
        document.querySelector(field_selector).value = (typeof address[fields[i]] !== 'undefined') ? address[fields[i]] : ''
      }
    }

  }

}
<!doctype html>
<html lang="en">
  <head>
      <link rel="stylesheet" href="postcoder.css" >   
      <script src="postcoder_address.js"></script>
  </head>
  <body>

    <form>
            
      <label for="txt_country">Country</label>
      <select id="txt_country">
        <option value="AU">Australia</option>
        <option value="AT">Austria</option>
        <option value="BE">Belgium</option>
        <option value="BZ">Belize</option>
        <option value="BJ">Benin</option>
        <option value="BM">Bermuda</option>
        <option value="BT">Bhutan</option>
        <option value="BO">Bolivia (Plurinational State of)</option>
        <option value="BQ">Bonaire, Sint Eustatius and Saba</option>
        <option value="BA">Bosnia and Herzegovina</option>
        <option value="BW">Botswana</option>
        <option value="BV">Bouvet Island</option>
        <option value="BR">Brazil</option>
        <option value="IO">British Indian Ocean Territory</option>
        <option value="BN">Brunei Darussalam</option>
        <option value="BG">Bulgaria</option>
        <option value="BF">Burkina Faso</option>
        <option value="BI">Burundi</option>
        <option value="CV">Cabo Verde</option>
        <option value="KH">Cambodia</option>
        <option value="CM">Cameroon</option>
        <option value="CA">Canada</option>
        <option value="KY">Cayman Islands</option>
        <option value="CF">Central African Republic</option>
        <option value="TD">Chad</option>
        <option value="CL">Chile</option>
        <option value="CN">China</option>
        <option value="CX">Christmas Island</option>
        <option value="CC">Cocos (Keeling) Islands</option>
        <option value="CO">Colombia</option>
        <option value="KM">Comoros</option>
        <option value="CD">Congo (the Democratic Republic of the)</option>
        <option value="CG">Congo</option>
        <option value="CK">Cook Islands</option>
        <option value="CR">Costa Rica</option>
        <option value="HR">Croatia</option>
        <option value="CU">Cuba</option>
        <option value="CW">Curaçao</option>
        <option value="CY">Cyprus</option>
        <option value="CZ">Czechia</option>
        <option value="CI">Côte d'Ivoire</option>
        <option value="DK">Denmark</option>
        <option value="DJ">Djibouti</option>
        <option value="DM">Dominica</option>
        <option value="DO">Dominican Republic</option>
        <option value="EC">Ecuador</option>
        <option value="EG">Egypt</option>
        <option value="SV">El Salvador</option>
        <option value="GQ">Equatorial Guinea</option>
        <option value="ER">Eritrea</option>
        <option value="EE">Estonia</option>
        <option value="SZ">Eswatini</option>
        <option value="ET">Ethiopia</option>
        <option value="FK">Falkland Islands [Malvinas]</option>
        <option value="FO">Faroe Islands</option>
        <option value="FJ">Fiji</option>
        <option value="FI">Finland</option>
        <option value="FR">France</option>
        <option value="GF">French Guiana</option>
        <option value="PF">French Polynesia</option>
        <option value="TF">French Southern Territories</option>
        <option value="GA">Gabon</option>
        <option value="GM">Gambia</option>
        <option value="GE">Georgia</option>
        <option value="DE">Germany</option>
        <option value="GH">Ghana</option>
        <option value="GI">Gibraltar</option>
        <option value="GR">Greece</option>
        <option value="GL">Greenland</option>
        <option value="GD">Grenada</option>
        <option value="GP">Guadeloupe</option>
        <option value="GU">Guam</option>
        <option value="GT">Guatemala</option>
        <option value="GG">Guernsey</option>
        <option value="GN">Guinea</option>
        <option value="GW">Guinea-Bissau</option>
        <option value="GY">Guyana</option>
        <option value="HT">Haiti</option>
        <option value="HM">Heard Island and McDonald Islands</option>
        <option value="VA">Holy See</option>
        <option value="HN">Honduras</option>
        <option value="HK">Hong Kong</option>
        <option value="HU">Hungary</option>
        <option value="IS">Iceland</option>
        <option value="IN">India</option>
        <option value="ID">Indonesia</option>
        <option value="IR">Iran (Islamic Republic of)</option>
        <option value="IQ">Iraq</option>
        <option value="IE">Ireland</option>
        <option value="IM">Isle of Man</option>
        <option value="IL">Israel</option>
        <option value="IT">Italy</option>
        <option value="JM">Jamaica</option>
        <option value="JP">Japan</option>
        <option value="JE">Jersey</option>
        <option value="JO">Jordan</option>
        <option value="KZ">Kazakhstan</option>
        <option value="KE">Kenya</option>
        <option value="KI">Kiribati</option>
        <option value="KP">Korea (the Democratic People's Republic of)</option>
        <option value="KR">Korea (the Republic of)</option>
        <option value="KW">Kuwait</option>
        <option value="KG">Kyrgyzstan</option>
        <option value="LA">Lao People's Democratic Republic</option>
        <option value="LV">Latvia</option>
        <option value="LB">Lebanon</option>
        <option value="LS">Lesotho</option>
        <option value="LR">Liberia</option>
        <option value="LY">Libya</option>
        <option value="LI">Liechtenstein</option>
        <option value="LT">Lithuania</option>
        <option value="LU">Luxembourg</option>
        <option value="MO">Macao</option>
        <option value="MG">Madagascar</option>
        <option value="MW">Malawi</option>
        <option value="MY">Malaysia</option>
        <option value="MV">Maldives</option>
        <option value="ML">Mali</option>
        <option value="MT">Malta</option>
        <option value="MH">Marshall Islands</option>
        <option value="MQ">Martinique</option>
        <option value="MR">Mauritania</option>
        <option value="MU">Mauritius</option>
        <option value="YT">Mayotte</option>
        <option value="MX">Mexico</option>
        <option value="FM">Micronesia (Federated States of)</option>
        <option value="MD">Moldova (the Republic of)</option>
        <option value="MC">Monaco</option>
        <option value="MN">Mongolia</option>
        <option value="ME">Montenegro</option>
        <option value="MS">Montserrat</option>
        <option value="MA">Morocco</option>
        <option value="MZ">Mozambique</option>
        <option value="MM">Myanmar</option>
        <option value="NA">Namibia</option>
        <option value="NR">Nauru</option>
        <option value="NP">Nepal</option>
        <option value="NL">Netherlands</option>
        <option value="NC">New Caledonia</option>
        <option value="NZ">New Zealand</option>
        <option value="NI">Nicaragua</option>
        <option value="NE">Niger</option>
        <option value="NG">Nigeria</option>
        <option value="NU">Niue</option>
        <option value="NF">Norfolk Island</option>
        <option value="MP">Northern Mariana Islands</option>
        <option value="NO">Norway</option>
        <option value="OM">Oman</option>
        <option value="PK">Pakistan</option>
        <option value="PW">Palau</option>
        <option value="PS">Palestine, State of</option>
        <option value="PA">Panama</option>
        <option value="PG">Papua New Guinea</option>
        <option value="PY">Paraguay</option>
        <option value="PE">Peru</option>
        <option value="PH">Philippines</option>
        <option value="PN">Pitcairn</option>
        <option value="PL">Poland</option>
        <option value="PT">Portugal</option>
        <option value="PR">Puerto Rico</option>
        <option value="QA">Qatar</option>
        <option value="MK">Republic of North Macedonia</option>
        <option value="RO">Romania</option>
        <option value="RU">Russian Federation</option>
        <option value="RW">Rwanda</option>
        <option value="RE">Réunion</option>
        <option value="BL">Saint Barthélemy</option>
        <option value="SH">Saint Helena, Ascension and Tristan da Cunha</option>
        <option value="KN">Saint Kitts and Nevis</option>
        <option value="LC">Saint Lucia</option>
        <option value="MF">Saint Martin (French part)</option>
        <option value="PM">Saint Pierre and Miquelon</option>
        <option value="VC">Saint Vincent and the Grenadines</option>
        <option value="WS">Samoa</option>
        <option value="SM">San Marino</option>
        <option value="ST">Sao Tome and Principe</option>
        <option value="SA">Saudi Arabia</option>
        <option value="SN">Senegal</option>
        <option value="RS">Serbia</option>
        <option value="SC">Seychelles</option>
        <option value="SL">Sierra Leone</option>
        <option value="SG">Singapore</option>
        <option value="SX">Sint Maarten (Dutch part)</option>
        <option value="SK">Slovakia</option>
        <option value="SI">Slovenia</option>
        <option value="SB">Solomon Islands</option>
        <option value="SO">Somalia</option>
        <option value="ZA">South Africa</option>
        <option value="GS">South Georgia and the South Sandwich Islands</option>
        <option value="SS">South Sudan</option>
        <option value="ES">Spain</option>
        <option value="LK">Sri Lanka</option>
        <option value="SD">Sudan</option>
        <option value="SR">Suriname</option>
        <option value="SJ">Svalbard and Jan Mayen</option>
        <option value="SE">Sweden</option>
        <option value="CH">Switzerland</option>
        <option value="SY">Syrian Arab Republic</option>
        <option value="TW">Taiwan (Province of China)</option>
        <option value="TJ">Tajikistan</option>
        <option value="TZ">Tanzania, United Republic of</option>
        <option value="TH">Thailand</option>
        <option value="TL">Timor-Leste</option>
        <option value="TG">Togo</option>
        <option value="TK">Tokelau</option>
        <option value="TO">Tonga</option>
        <option value="TT">Trinidad and Tobago</option>
        <option value="TN">Tunisia</option>
        <option value="TR">Turkey</option>
        <option value="TM">Turkmenistan</option>
        <option value="TC">Turks and Caicos Islands</option>
        <option value="TV">Tuvalu</option>
        <option value="UG">Uganda</option>
        <option value="UA">Ukraine</option>
        <option value="AE">United Arab Emirates</option>
        <option value="GB" selected>United Kingdom</option>
        <option value="UM">United States Minor Outlying Islands</option>
        <option value="US">United States of America</option>
        <option value="UY">Uruguay</option>
        <option value="UZ">Uzbekistan</option>
        <option value="VU">Vanuatu</option>
        <option value="VE">Venezuela (Bolivarian Republic of)</option>
        <option value="VN">Viet Nam</option>
        <option value="VG">Virgin Islands (British)</option>
        <option value="VI">Virgin Islands (U.S.)</option>
        <option value="WF">Wallis and Futuna</option>
        <option value="EH">Western Sahara</option>
        <option value="YE">Yemen</option>
        <option value="ZM">Zambia</option>
        <option value="ZW">Zimbabwe</option>
      </select>


      <label for="txt_search">Search for an address or postcode</label>
      <button type="button" id="btn_search">
          Search
      </button>
      <div class="search_wrap">
          <input type="text" id="txt_search">
      </div>

      <div id="address_selection_container"></div>

      <div id="no_result_message">
          Address not found, please enter manually.
      </div>

      <label for="txt_organsation">Organisation</label>
      <input type="text" id="txt_organsation">


      <label for="txt_addressline1">Address</label>
      <input type="text" id="txt_addressline1">
      <input type="text" id="txt_addressline2">
      <input type="text" id="txt_addressline3">


      <label for="txt_posttown">Town</label>
      <input type="text" id="txt_posttown">


      <label for="txt_postcode">Postcode</label>
      <input type="text" id="txt_postcode">
      
    </form>


    <script>
        
        new PostcoderAddress({
            apikey: 'PCW45-12345-12345-1234X', 
            searchterm: '#txt_search', // query selector of the searchterm input field
            addressselectioncontainer: '#address_selection_container', // container for the address selection drop down
            noresultmessage: '#no_result_message',
            country: '#txt_country',  // Country select list; leave blank if not using a country select list 
            countrycode: '', // Hard code if not using a country select list; leave blank otherwise 
            searchbutton: '#btn_search', 
            organisation: '#txt_organsation',  // Leave blank if form does not have a separate organisation field 
            addressline1: '#txt_addressline1', 
            addressline2: '#txt_addressline2',  // Leave blank if form does not have an addressline2 
            addressline3: '#txt_addressline3',  // Leave blank if form does not have an addressline3 
            //addressline4: '',  // Leave blank if form does not have an addressline4
            county: '', // Leave blank if form does not have a county
            posttown: '#txt_posttown', 
            postcode: '#txt_postcode' 
        })

    </script>


  </body>
</html>
input, select {
	display: block;
	box-sizing: border-box;
	width: 100%;
	padding: 10px;
	height: 40px;
	margin-bottom: 0.5em;
	border-width: 1px;
	border-style: solid;
	border-color: lightgray;
}

.search_wrap {
	overflow: hidden;
}

.search_wrap div {
	font-size: 0.75em;
}

button {
	padding: 8px;
	margin-left: 0.5em;
	float:  right;
	font-family: sans-serif;
}

label {
	display: block;
	margin-top: 1.25em;
	margin-bottom: 0.25em;
}
select {
	position: relative;
	z-index: 1;
	padding-right: 40px;
}

.isvalid:after {
	content: '\2713';
	color: green;
}

.notvalid:after {
	content: '\2717';
    color: red;
}   

#successindicator {
	float:  right;
	margin-left: 0.5em;
	display: flex;
  	justify-content: center;
  	align-content: center;
  	flex-direction: column;
  	height: 40px;
}

#json_result_container {
	margin: 5em 0 0;
    background-color: #eee;
	color: #333;
    /* border: solid lightgrey 1px; */
	padding: 1em;
	overflow: auto;
}

#autocomplete_wrap{
	position: relative;
}

#suggestion_list{
	position:  absolute;
	background-color: #fff;
	outline: -webkit-focus-ring-color auto 1px;
	list-style-type: none;
  	margin: 0;
  	padding: 0;
  	max-height:  400px;
  	overflow-y: auto;
}

#suggestion_list li{
	cursor: pointer;
	padding: 10px 5px;
}

#suggestion_list li.header{
	border-bottom: 2px solid #ddd;
}

#suggestion_list li:hover, #suggestion_list li.selected{
	background-color: #ddd;
}

#suggestion_list li span.location{
	font-size: 0.75em;
	color: #666;
}

.arrow {
 	border: solid black;
	border-width: 0 3px 3px 0;
	display: inline-block;
	padding: 3px;
}

.left {
	margin-left: 3px;
	transform: rotate(135deg);
	-webkit-transform: rotate(135deg);
}

.address{
	height: 140px;
	margin: 8px;
}

.map {
	height: 300px;
	width: 100%;
}

body {
	font-family: sans-serif;
	padding: 0;
	margin: 0;
}

Download sample code

Download a zip file of the sample code for address looukp using javascript.

Download zip

Tables

FieldDescriptionExample
apikeyYour API keyPCW45-12345-12345-1234X
formatSets the format of the response, xml or json (default unless "application/xml" header is detected)format=json
summarylineA summary of the address, ideal for displaying in a drop-down listAllies Computing Ltd, Manor Farm Barns, Fox Road, Framingham Pigot, Norwich, Norfolk, NR14 7PZ
nextpageThe page number for the next page of results to request2
aliasA true or false indicating whether the address is a Royal Mail Alias recordtrue
availablecreditsThe number of credits remaining99999

Notifications

Here you can find a selection of the notifications available to use to alert users of specific information in the documentation.

Note: Lorem ipsum dolor sit, amet consectetur adipisicing elit. Architecto sed, velit aliquid repellat vero est id numquam placeat impedit doloribus consectetur illum, porro similique blanditiis. Quasi fugiat id reiciendis quibusdam! Here's a link.
Alert: Lorem ipsum dolor sit, amet consectetur adipisicing elit. Architecto sed, velit aliquid repellat vero est id numquam placeat impedit doloribus consectetur illum, porro similique blanditiis. Quasi fugiat id reiciendis quibusdam! Here's a link.
Error: Lorem ipsum dolor sit, amet consectetur adipisicing elit. Architecto sed, velit aliquid repellat vero est id numquam placeat impedit doloribus consectetur illum, porro similique blanditiis. Quasi fugiat id reiciendis quibusdam! Here's a link.
Success! Lorem ipsum dolor sit, amet consectetur adipisicing elit. Architecto sed, velit aliquid repellat vero est id numquam placeat impedit doloribus consectetur illum, porro similique blanditiis. Quasi fugiat id reiciendis quibusdam! Here's a link.

Buttons

Sometimes a button will be needed for a call to action. Listed below are the options for button use and use cases for specific types.

Standard button Download button

Primary button

Note: This button type is mainly used for "Start a free trial" as a primary call to action.
Primary button

Secondary button

Note: This button type is useful for a soft call to action, say buying credits.
Secondary button

Next / Previous Page Nav

...