|
| 1 | +--- |
| 2 | +title: Form Errors |
| 3 | +category: Guides |
| 4 | +order: 7 |
| 5 | +--- |
| 6 | + |
| 7 | +# Adding Error Messages to Form Components |
| 8 | + |
| 9 | +InstUI offers a range of form elements and all of them have a similar API to handle error/hint/success messages. These components use the `messages` prop with the following type definition: |
| 10 | + |
| 11 | +```ts |
| 12 | +--- |
| 13 | +type: code |
| 14 | +--- |
| 15 | +type FormMessages = { |
| 16 | + type: |
| 17 | + | 'newError' |
| 18 | + | 'error' |
| 19 | + | 'hint' |
| 20 | + | 'success' |
| 21 | + | 'screenreader-only' |
| 22 | + text: React.ReactNode |
| 23 | +}[] |
| 24 | +``` |
| 25 | +
|
| 26 | +So a basic example would look something like this: |
| 27 | +
|
| 28 | +```ts |
| 29 | +--- |
| 30 | +type: example |
| 31 | +--- |
| 32 | +const PasswordExample = () => { |
| 33 | + const [password, setPassword] = useState('') |
| 34 | + const messages = password.length < 6 |
| 35 | + ? [{type: 'newError', text: 'Password have to be at least 6 characters long!'}] |
| 36 | + : [] |
| 37 | + return ( |
| 38 | + <TextInput |
| 39 | + renderLabel="Password" |
| 40 | + type="password" |
| 41 | + messages={messages} |
| 42 | + onChange={(event, value) => { setPassword(value) }} |
| 43 | + /> |
| 44 | + ) |
| 45 | +} |
| 46 | + |
| 47 | +render(<PasswordExample/>) |
| 48 | +``` |
| 49 | + |
| 50 | +However you might have noticed from the type definition that a message can be `error` and `newError` type. This is due to compatibility reasons. `error` is the older type and does not meet accessibility requirements, `newError` (hance the name) is the newer and more accessible format. |
| 51 | + |
| 52 | +We wanted to allow users to start using the new format without making it mandatory, but after the introductory period `newError` will be deprecated and `error` type will be changed to look and behave the same way. |
| 53 | + |
| 54 | +With this update we also introduced the "required asterisk" which will display an `*` character next to field labels that are required. This update is not opt-in and will apply to **all** InstUI form components so if you were relying on a custom solution for this feature before, you need to remove that to avoid having double asterisks. |
| 55 | + |
| 56 | +Here are examples with different form components: |
| 57 | + |
| 58 | +```ts |
| 59 | +--- |
| 60 | +type: example |
| 61 | +--- |
| 62 | +const Example = () => { |
| 63 | + const [showError, setShowError] = useState(true) |
| 64 | + const [showNewError, setShowNewError] = useState(true) |
| 65 | + const [showLongError, setShowLongError] = useState(false) |
| 66 | + const [isRequired, setIsRequired] = useState(true) |
| 67 | + |
| 68 | + const messages = showError |
| 69 | + ? [{type: showNewError ? 'newError' : 'error', text: showLongError ? 'Long error. Lorem ipsum dolor sit amet consectetur adipisicing elit. Dignissimos voluptas, esse commodi eos facilis voluptatibus harum exercitationem. Et magni est consectetur, eveniet veniam unde! Molestiae labore libero sapiente ad ratione.' : 'Short error message'}] |
| 70 | + : [] |
| 71 | + |
| 72 | + const handleSettingsChange = (v) => { |
| 73 | + setShowError(v.includes('showError')) |
| 74 | + setShowNewError(v.includes('showNewError')) |
| 75 | + setShowLongError(v.includes('showLongError')) |
| 76 | + setIsRequired(v.includes('isRequired')) |
| 77 | + } |
| 78 | + |
| 79 | + return ( |
| 80 | + <div> |
| 81 | + <CheckboxGroup |
| 82 | + name="errorOptions" |
| 83 | + description="Error message options" |
| 84 | + onChange={handleSettingsChange} |
| 85 | + defaultValue={['showError', 'showNewError', 'isRequired']} |
| 86 | + > |
| 87 | + <Checkbox label="Show error message" value="showError"/> |
| 88 | + <Checkbox label="Use the new error type" value="showNewError" /> |
| 89 | + <Checkbox label="Use long message" value="showLongError" /> |
| 90 | + <Checkbox label="Make fields required" value="isRequired" /> |
| 91 | + </CheckboxGroup> |
| 92 | + <div style={{display: 'flex', gap: '2rem', marginTop: '3rem', flexDirection: 'column'}}> |
| 93 | + |
| 94 | + <TextInput renderLabel="TextInput" messages={messages} isRequired={isRequired}/> |
| 95 | + |
| 96 | + <NumberInput renderLabel="NumberInput" messages={messages} isRequired={isRequired}/> |
| 97 | + |
| 98 | + <TextArea messages={messages} label="TextArea" required={isRequired}/> |
| 99 | + |
| 100 | + <Checkbox label="Checkbox" isRequired={isRequired} messages={messages}/> |
| 101 | + |
| 102 | + <Checkbox label={`Checkbox (variant="toggle")`} variant="toggle" isRequired={isRequired} messages={messages}/> |
| 103 | + |
| 104 | + <CheckboxGroup |
| 105 | + name="CheckboxGroup" |
| 106 | + messages={messages} |
| 107 | + description="CheckboxGroup" |
| 108 | + > |
| 109 | + <Checkbox label="Checkbox 1" value="checkbox1"/> |
| 110 | + <Checkbox label="Checkbox 2" value="checkbox2"/> |
| 111 | + <Checkbox label="Checkbox 3" value="checkbox3"/> |
| 112 | + </CheckboxGroup> |
| 113 | + |
| 114 | + <RadioInputGroup name="radioInputGroup" description="RadioInputGroup" messages={messages} isRequired={isRequired}> |
| 115 | + <RadioInput |
| 116 | + label="RadioInput 1" |
| 117 | + value="radioInput1" |
| 118 | + /> |
| 119 | + <RadioInput |
| 120 | + label="RadioInput 2" |
| 121 | + value="radioInput2" |
| 122 | + /> |
| 123 | + <RadioInput |
| 124 | + label="RadioInput 3" |
| 125 | + value="radioInput3" |
| 126 | + /> |
| 127 | + </RadioInputGroup> |
| 128 | + |
| 129 | + <FileDrop messages={messages} renderLabel="FileDrop" /> |
| 130 | + |
| 131 | + <ColorPicker |
| 132 | + label="ColorPicker" |
| 133 | + placeholderText="Enter HEX" |
| 134 | + isRequired={isRequired} |
| 135 | + renderMessages={() => messages} |
| 136 | + /> |
| 137 | + |
| 138 | + </div> |
| 139 | + </div> |
| 140 | + ) |
| 141 | +} |
| 142 | + |
| 143 | +render(<Example/>) |
| 144 | +``` |
0 commit comments