On this page
@addTagHelper *, Webority.Ui.RazorBasic
Type a hex value or pick a colour with the swatch; both controls edit the same value.
Sizes
Use md for most fields, sm inside dense settings rows and lg for a marketing-scale field.
States
Required, helper text and error sit on the text box, like every other field in a form.
Every option
Every value of every prop, one cell each.
value: complete vs incomplete hex
value="#4F46E5": complete, swatch matchesvalue="#4F4": incomplete, swatch falls back to #000000value="": empty, swatch falls back to #000000defaultValue
value="#E11D48": React form is defaultValue, the field starts with itonChange
onChange={(hex) => …}: React only, Razor posts the value with the formlabel
label="Accent colour"label omitted: swatch aria-label falls back to "Colour"state: required, helperText, error, disabled
(default)requiredhelper-texterrorerror and helper-text: both showdisabledrequired and erroroptional
optionaloptional and required: required wins, no (optional)name
name="accent": posts with the form, no visible changeid
id="accent-hex": sets the hex box id, no visible changesize
size="sm"size="md" (default)size="lg"readOnly
read-only="true": shows the value, blocks editing, the value still postsloading
loading="true": busy state, blocks input while data loadshelp
help="…": info tip beside the labelhelpLabel
help-label="More information" (default)help-label="Accent help": names the info tip buttoncolourLabel
colour-label="Tint": names the swatch when there is no labelcolourPickerLabel
colour-picker-label="{label}, tint picker": names the swatch for screen readersoptionalLabel
optional-label="(not required)": the text added to an optional labelclassName
input-class="wide-hex": added to the hex text inputfieldClassName
class="mb-0" (React: fieldClassName): added to the field wrapperGuidance
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
Says what the colour affects. A user picking blind cannot tell whether they are about to change one button or the whole portal.
“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.
18 props. The 5 most used come first.
Used on most screens 5 props
| Prop | Type | Default | Description |
|---|---|---|---|
| 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
| Prop | Type | Default | Description |
|---|---|---|---|
| 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 pairsSay what the colour affects
Says what the colour affects. A user picking blind cannot tell whether they are about to change one button or the whole portal.
“Colour” of what? And with no helper text, the user has to save and go looking to find out what changed.