Skip to main content

ns-selector

Introduction#

Selectors are used to group an image or illustration with a label into a card. They showcase a product, service or option, which users can select. They can function as single, or multiple selection for the user.

Content guidance#

Selector - Illustration#

Selector - Illustration

KeyField typeGuidelines
ALabelThe label should describe the selection being made using the most concise content possible. The recommended length is 21 characters maximum.
BHeadingThe heading can provide an expanded description of the item being selected. The recommended length is between 3 and 21 characters. This heading should use a light font weight to allow the emphasis on the label.
CParagraphThe paragraph is mandatory when using with illustration. The illustration should be used purely as decorative in ns-selector and it doesn't come with an alternative description for assistive technology like screen readers. The paragraph should provide information to make the selector more accessible. The recommended length is 1 concise paragraph or 5 short bullet points, not exceeding 125 characters in total. Can contain bold copy <b>, inline links <a>, lists <ul> <ol>, and a caveat at the end of the relevant paragraph if required <a href="#caveat">1</a>.
DIllustrationUse to support and highlight the content. The illustration should relate to the product or service you are talking about. The specification table has a list of options.
EKeylineAn optional colour keyline can be added to distinguish and draw attention to your selectors.
FPillYou can use a pill to promote an option that has something special like a discount, a promotion or a because it's eco-friendly. Use the pill the h3 and the list. Try not to add a pill to each option as it may lose its attention grabbing power.
GExpandersAn optional addition of an ns-expander component within the selector allows for more detail to be discoverable. It consists of a heading and an anonymous content slot. When the heading is clicked the component opens to reveal the content. When in an open state, clicking the heading will hide the content.

Selector - Image#

Selector - Image

KeyField typeGuidelines
ALabelThe label should describe the selection being made using the most concise content possible. The recommended length is 21 characters maximum.
BParagraphThe recommended length is 1 concise paragraph or 5 short bullet points, not exceeding 125 characters in total. Can contain bold copy <b>, inline links <a>, lists <ul> <ol>, and a caveat at the end of the relevant paragraph if required <a href="#caveat">1</a>.
CImageThis is the image that will be used above the ns-card. It should have an aspect ratio of 16:9, the dimensions should be 640x360px, the file type should be jpg, and the file size should be no more than 50kb. If this image provides visualisation to the label (Key A), paragraph section (Key B) is optional.
DKeylineAn optional colour keyline can be added to distinguish and draw attention to your selectors.
EExpandersAn optional addition of an ns-expander component within the selector allows for more detail to be discoverable. It consists of a heading and an anonymous content slot. When the heading is clicked the component opens to reveal the content. When in an open state, clicking the heading will hide the content.

Image guidance#

ComponentVariantRatioDimensionsSizeTypePlaceholder
ns-selectorn/a16:9640x360px< 50kbjpegns-selector-640x360px

Best practice#

πŸ’š Do'sπŸ’” Don'ts
Use if you need to support the label with an imageMix radio and checkboxes
Use if you need to support the label with an illustrationUse if the image or illustration make the selection harder to understand
Use a heading within the content when providing supporting copyAdd too much content, they should not be miniature web pages
Use inline text links into supporting content if necessaryUse without an image or an illustration
Bolden key messages eg. price within heading to highlightUse imagery within ns-selector with copy embedded inside
Use a radio button or checkboxUse an image and an illustration together
Use expanders if you need to include more detailsAdd a decoration behind the selectors
Use paragraph for description when using illustrationUse more than 5 expanders on a selector

Considerations of best practices#

  • When deciding to use the ns-selector, it’s important to consider whether a radio or checkbox button itself would be more appropriate.
  • In a many cases, a simple radio button or checkbox is all the user needs to make the choice. Only use the ns selector when adding more supporting information makes the decision for the user easier.
  • If you are using the ns-selector with an illustration, it's important to make sure you are using a Nucleus illustration. View illustrations in Storybook.
  • Make sure the paragraph section is added for more description when illustration is used.
  • Make sure the supporting copy is clear and concise.
  • Make sure the labels explain exactly what the user is selecting. If all content is removed other than the label, then the user would still understand what they are selecting.
  • If using the optional Expander, keep the content concise – you can use lists in the content to help. Be mindful that once a heading is expanded it forces the bottom of that selector down and that of any other instances in the row.

Usage#

View example on Storybook

Component placement#

The ns-selector component can be used in the following components:

When used in ns-column, ns-column must be a child of ns-inputter:

<ns-inputter>
<ns-column hockeypitch="3">
<ns-selector>...</ns-selector>
<ns-selector>...</ns-selector>
<ns-selector>...</ns-selector>
</ns-column>
</ns-inputter>

Specification#

AttributeTypeDefaultOptionsDescription
checkedstringCheck the value.
decorationstringSee Illustration component in StorybookIllustration that is show in the section type card
imagestringOptional image
valueanyValue of selection
keylinestringnoneblue, yellow, green-light, cyan, redAdd a gradient across the top of the selector
SlotsTypeDescription
descriptiondivMandatory when using with decoration attribute and optional when using with image attribute
anonymousinput label

Design Tokens

You can change the branded look and feel of the ns-selector by modifying these options in the design tokens.

Read more about design tokens in our getting started guide.

{
  "theme": "white",
  "border-color": "#C8C9C7",
  "checked-border-color": "#005EB8",
  "keylines": [
    "green-light",
    "blue",
    "cyan",
    "yellow",
    "red"
  ],
  "label": {
    "typography": "action"
  }
}

Feedback#

  • Do you have insights or concerns to share? You can raise an issue via Github bugs.
  • See all the issues already raised via Github issues.

πŸ’© πŸŽ‰ πŸ¦„ You can also contact the team on Slack on the #product-nucleus channel!

Related links#