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#
| Key | Field type | Guidelines |
|---|---|---|
| A | Label | The label should describe the selection being made using the most concise content possible. The recommended length is 21 characters maximum. |
| B | Heading | The 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. |
| C | Paragraph | The 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>. |
| D | Illustration | Use 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. |
| E | Keyline | An optional colour keyline can be added to distinguish and draw attention to your selectors. |
| F | Pill | You 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. |
| G | Expanders | An 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#
| Key | Field type | Guidelines |
|---|---|---|
| A | Label | The label should describe the selection being made using the most concise content possible. The recommended length is 21 characters maximum. |
| B | Paragraph | 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>. |
| C | Image | This 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. |
| D | Keyline | An optional colour keyline can be added to distinguish and draw attention to your selectors. |
| E | Expanders | An 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#
| Component | Variant | Ratio | Dimensions | Size | Type | Placeholder |
|---|---|---|---|---|---|---|
ns-selector | n/a | 16:9 | 640 x 360px | <50kb | jpeg | ns-selector-640x360px |
Best practice#
| 💚 Do's | 💔 Don'ts |
|---|---|
| Use if you need to support the label with an image | Mix radio and checkboxes |
| Use if you need to support the label with an illustration | Use if the image or illustration make the selection harder to understand |
| Use a heading within the content when providing supporting copy | Add too much content, they should not be miniature web pages |
| Use inline text links into supporting content if necessary | Use imagery within ns-selector with copy embedded inside |
| Use a radio button or checkbox | Use an image and an illustration together |
| Use expanders if you need to include more details | Add a decoration behind the selectors |
| Use paragraph for description when using illustration | Use 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
ns-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#
Component placement#
The ns-selector component can be used in the following components:
If you have more than one ns-selector, place them into ns-column.
When used in ns-column, ns-column must be a child of ns-inputter:
Specification#
| Attribute | Property | Type | Default | Options | Description |
|---|---|---|---|---|---|
decoration | decoration | string | See Illustration component in Storybook | Illustration that is show in the section type card | |
image | image | string | Optional image | ||
keyline | keyline | string | none | cyan, lime, navy, blue, forest, slate, orange, red, yellow | Add a colour across the top of the selector |
| Slots | Type | Description |
|---|---|---|
description | div | Mandatory when using with decoration attribute and optional when using with image attribute |
anonymous | input label |
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.
💩 🎉 🦄 If you have any questions, contact us on Microsoft Teams in the Nucleus Design System channels.