Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Basic

Type a hex value or pick a colour with the swatch; both controls edit the same value.

Picking an accent
Show code
<app-color-field label="Accent colour" name="Accent" value="#4F46E5"></app-color-field>

Sizes

Use md for most fields, sm inside dense settings rows and lg for a marketing-scale field.

Small, medium and large
Show code
<app-color-field label="Small" name="S1" value="#4F46E5" size="Sm"></app-color-field>
<app-color-field label="Medium (default)" name="S2" value="#4F46E5"></app-color-field>
<app-color-field label="Large" name="S3" value="#4F46E5" size="Lg"></app-color-field>

States

Required, helper text and error sit on the text box, like every other field in a form.

Required, helper text, error and disabled
Used for buttons and links across your portal.
Enter a 6-digit hex, e.g. #4F46E5
Show code
<app-color-field label="Accent colour" name="A1" value="#4F46E5" required="true"></app-color-field>
<app-color-field label="Accent colour" name="A2" value="#4F46E5" helper-text="Used for buttons and links across your portal."></app-color-field>
<app-color-field label="Accent colour" name="A3" value="#4F46E5" error="Enter a 6-digit hex, e.g. #4F46E5"></app-color-field>
<app-color-field label="Locked accent" name="A4" value="#4F46E5" disabled="true"></app-color-field>

Every option

Every value of every prop, one cell each.

value: complete vs incomplete hex

value="#4F46E5": complete, swatch matches
value="#4F4": incomplete, swatch falls back to #000000
value="": empty, swatch falls back to #000000

defaultValue

value="#E11D48": React form is defaultValue, the field starts with it

onChange

onChange={(hex) => …}: React only, Razor posts the value with the form

label

label="Accent colour"
label omitted: swatch aria-label falls back to "Colour"

state: required, helperText, error, disabled

(default)
required
helper-text
Used for buttons and links.
error
Enter a 6-digit hex, e.g. #4F46E5
error and helper-text: both show
Used for buttons and links.
Enter a 6-digit hex, e.g. #4F46E5
disabled
required and error
Required

optional

optional
optional and required: required wins, no (optional)

name

name="accent": posts with the form, no visible change

id

id="accent-hex": sets the hex box id, no visible change

size

size="sm"
size="md" (default)
size="lg"

readOnly

read-only="true": shows the value, blocks editing, the value still posts

loading

loading="true": busy state, blocks input while data loads

help

help="…": info tip beside the label

helpLabel

help-label="More information" (default)
help-label="Accent help": names the info tip button

colourLabel

colour-label="Tint": names the swatch when there is no label

colourPickerLabel

colour-picker-label="{label}, tint picker": names the swatch for screen readers

optionalLabel

optional-label="(not required)": the text added to an optional label

className

input-class="wide-hex": added to the hex text input

fieldClassName

class="mb-0" (React: fieldClassName): added to the field wrapper

Guidance

What to do, and what to avoid.

Use it when

  • The user genuinely needs an arbitrary colour, such as a brand accent or a tag colour.
  • A hex from a brand guide will be pasted in.
  • The field sits in a settings or theming form.

Reach for something else when

  • There is a fixed palette to choose from (AppChoiceChip or AppChoiceCard). → AppChoiceChip
  • The colour carries meaning (status, severity). Meaning belongs to a token, not a user-picked hex. → AppStatusBadge
  • It is any other single-line value. → AppInput

Say what the colour affects

Do
Used for buttons and links.

Says what the colour affects. A user picking blind cannot tell whether they are about to change one button or the whole portal.

Avoid

“Colour” of what? And with no helper text, the user has to save and go looking to find out what changed.

Reference

Try every prop, read the full list, and check keyboard and screen reader behaviour.

sm md lg
React, generated from the controls
<AppColorField label="Accent colour" name="pg-color" value="#4F46E5" onChange={setAccent} />
Razor, the same props
<app-color-field label="Accent colour" name="pg-color" value="#4F46E5" />

18 props. The 5 most used come first.

Used on most screens 5 props

PropTypeDefaultDescription
valuedefault #000000 string #000000 Hex colour, for example #4F46E5.
labeldefault - string - Field label.
requireddefault false bool false Marks the field as required.
errordefault - string - Error message shown under the field.
helper-textdefault - string - Helper text shown under the field.

Less common 13 props

PropTypeDefaultDescription
namedefault - string - Form field name on the text box, the control that posts.
iddefault auto-generated string auto-generated Element id of the hex text box. Defaults to a generated id, not name.
optionaldefault false bool false Ends the label with (optional) when the field is not required. Required wins when both are set.
disableddefault false bool false The field cannot change.
sizedefault md sm | md | lg md Control size. sm and lg resize the swatch and the hex box together.
read-onlydefault false bool false Shows the value but blocks editing. The value still posts.
loadingdefault false bool false Shows a busy state and blocks input while data loads.
helpdefault - string - Info-tip content shown beside the label.
help-labeldefault More information string More information The accessible name of the info-tip button.
colour-labeldefault Colour string Colour Replaces the built-in English text, for other languages.
colour-picker-labeldefault {label}, colour picker string {label}, colour picker Replaces the built-in English text, for other languages. {label} is the field label.
optional-labeldefault (optional) string (optional) Replaces the built-in English text, for other languages.
input-classdefault - string - Extra classes on the control itself (the hex input). The plain class attribute merges onto the field wrapper instead.

Screen reader

3 notes
  • The hex text box is the labelled control and the field that posts; the label points at it and the required mark follows the label.
  • The swatch has its own accessible name, the label followed by colour picker (or Colour when there is no label), and is skipped by the tab key.
  • An error sets the text box invalid and describes it with the error text; without an error, the helper text describes it.

Do and avoid

1 pairs

Say what the colour affects

Do
Used for buttons and links.

Says what the colour affects. A user picking blind cannot tell whether they are about to change one button or the whole portal.

Avoid

“Colour” of what? And with no helper text, the user has to save and go looking to find out what changed.