Allow check fields and selectable fields to render as required #487

Users may find themselves in a situation where the input is not required (i.e. making the input checked), but they also don't want to render the field as optional because not choosing an option can be perfectly valid. For this case, there is the `renderAsRequired` prop. This affects `CheckboxField`, `Radio`, `SelectField`, and `Toggle`. Closes #487
react-ui-org · Jan 24, 2025 · d0d9758 · d0d9758
1 parent ca1c36a
commit d0d9758
Show file tree

Hide file tree

Showing 16 changed files with 435 additions and 15 deletions.
diff --git a/src/components/CheckboxField/CheckboxField.jsx b/src/components/CheckboxField/CheckboxField.jsx
@@ -15,6 +15,7 @@ export const CheckboxField = React.forwardRef((props, ref) => {
     isLabelVisible,
     label,
     labelPosition,
+    renderAsRequired,
     required,
     validationState,
     validationText,
@@ -30,7 +31,7 @@ export const CheckboxField = React.forwardRef((props, ref) => {
         context && context.layout === 'horizontal' ? styles.isRootLayoutHorizontal : styles.isRootLayoutVertical,
         labelPosition === 'before' && styles.hasRootLabelBefore,
         disabled && styles.isRootDisabled,
-        required && styles.isRootRequired,
+        (renderAsRequired || required) && styles.isRootRequired,
         getRootValidationStateClassName(validationState, styles),
       )}
       htmlFor={id}
@@ -82,6 +83,7 @@ CheckboxField.defaultProps = {
   id: undefined,
   isLabelVisible: true,
   labelPosition: 'after',
+  renderAsRequired: false,
   required: false,
   validationState: null,
   validationText: null,
@@ -120,7 +122,11 @@ CheckboxField.propTypes = {
    */
   labelPosition: PropTypes.oneOf(['before', 'after']),
   /**
-   * If `true`, the input will be required.
+   * If `true`, the input will be rendered as if it was required.
+   */
+  renderAsRequired: PropTypes.bool,
+  /**
+   * If `true`, the input will be made and rendered as required, regardless of the `renderAsRequired` prop.
    */
   required: PropTypes.bool,
   /**

diff --git a/src/components/CheckboxField/README.md b/src/components/CheckboxField/README.md
@@ -186,6 +186,81 @@ React.createElement(() => {
 });
 ```
 
+### Required State
+
+The required state indicates that the input is mandatory. Required fields
+display an asterisk `*` after the label by default.
+
+```docoff-react-preview
+React.createElement(() => {
+  const [agree, setAgree] = React.useState(true);
+  return (
+    <CheckboxField
+      checked={agree}
+      label="I agree"
+      onChange={() => setAgree(!agree)}
+      required
+    />
+  );
+});
+```
+
+#### Styling the Required State
+
+All form fields in React UI can be
+[styled](/docs/customize/theming/forms/#required-state)
+to indicate the required state.
+
+However, you may find yourself in a situation where a form field is valid in
+both checked and unchecked states, for example to turn on or off a feature.
+If your project uses the label color as the primary means to indicate the
+required state of input fields and the usual asterisk `*` is omitted, you may
+want to keep the label color consistent for both states to avoid confusion.
+
+For this edge case, there is the `renderAsRequired` prop:
+
+```docoff-react-preview
+React.createElement(() => {
+  const [optional, setOptional] = React.useState(false);
+  const [renderAsRequired, setRenderAsRequired] = React.useState(false);
+  return (
+    <React.Fragment>
+      <style>
+      {`
+        .example {
+          display: flex;
+          flex-wrap: wrap;
+          gap: 1rem 0.5rem;
+        }
+
+        .example--themed-form-fields {
+          --rui-FormField__label__color: var(--rui-color-text-secondary);
+          --rui-FormField--required__label__color: var(--rui-color-text-primary);
+          --rui-FormField--required__sign: '';
+        }
+      `}
+      </style>
+      <div class="example example--themed-form-fields">
+        <CheckboxField
+          checked={optional}
+          label="This field is optional"
+          onChange={() => setOptional(!optional)}
+        />
+        <CheckboxField
+          checked={renderAsRequired}
+          label="This field is optional but looks like required"
+          onChange={() => setRenderAsRequired(!renderAsRequired)}
+          renderAsRequired
+        />
+      </div>
+    </React.Fragment>
+  );
+});
+```
+
+It renders the field as if it was required, but doesn't add the `required`
+attribute to the actual input.
+
 ### Disabled State
 
 Disabled state makes the input unavailable.

diff --git a/src/components/CheckboxField/__tests__/CheckboxField.test.jsx b/src/components/CheckboxField/__tests__/CheckboxField.test.jsx
@@ -11,6 +11,7 @@ import { helpTextPropTest } from '../../../../tests/propTests/helpTextPropTest';
 import { formLayoutProviderTest } from '../../../../tests/providerTests/formLayoutProviderTest';
 import { isLabelVisibleTest } from '../../../../tests/propTests/isLabelVisibleTest';
 import { labelPropTest } from '../../../../tests/propTests/labelPropTest';
+import { renderAsRequiredPropTest } from '../../../../tests/propTests/renderAsRequiredPropTest';
 import { requiredPropTest } from '../../../../tests/propTests/requiredPropTest';
 import { validationStatePropTest } from '../../../../tests/propTests/validationStatePropTest';
 import { validationTextPropTest } from '../../../../tests/propTests/validationTextPropTest';
@@ -43,6 +44,7 @@ describe('rendering', () => {
     ],
     ...isLabelVisibleTest(),
     ...labelPropTest(),
+    ...renderAsRequiredPropTest,
     ...requiredPropTest,
     ...validationStatePropTest,
     ...validationTextPropTest,

diff --git a/src/components/Radio/README.md b/src/components/Radio/README.md
@@ -237,6 +237,109 @@ have.
   })
 ```
 
+### Required State
+
+The required state indicates that the input is mandatory.
+
+```docoff-react-preview
+React.createElement(() => {
+  const [fruit, setFruit] = React.useState('apple');
+  return (
+    <Radio
+      label="Your favourite fruit"
+      onChange={(e) => setFruit(e.target.value)}
+      options={[
+        {
+          label: 'Apple',
+          value: 'apple',
+        },
+        {
+          label: 'Banana',
+          value: 'banana',
+        },
+        {
+          label: 'Grapefruit',
+          value: 'grapefruit',
+        },
+      ]}
+      value={fruit}
+      required
+    />
+  );
+})
+```
+
+#### Styling the Required State
+
+All form fields in React UI can be
+[styled](/docs/customize/theming/forms/#required-state)
+to indicate the required state.
+
+However, you may find yourself in a situation where a form field is valid in
+both selected and unselected states, for example to turn on or off a feature.
+If your project uses the label color as the primary means to indicate the
+required state of input fields and the usual asterisk `*` is omitted, you may
+want to keep the label color consistent for both states to avoid confusion.
+
+For this edge case, there is the `renderAsRequired` prop:
+
+```docoff-react-preview
+React.createElement(() => {
+  const [fruit, setFruit] = React.useState('apple');
+  const options = [
+    {
+      label: 'Apple',
+      value: 'apple',
+    },
+    {
+      label: 'Banana',
+      value: 'banana',
+    },
+    {
+      label: 'Grapefruit',
+      value: 'grapefruit',
+    },
+  ];
+  return (
+   <React.Fragment>
+      <style>
+      {`
+        .example {
+          display: flex;
+          flex-wrap: wrap;
+          gap: 1rem 0.5rem;
+        }
+
+        .example--themed-form-fields {
+          --rui-FormField__label__color: var(--rui-color-text-secondary);
+          --rui-FormField--required__label__color: var(--rui-color-text-primary);
+          --rui-FormField--required__sign: '';
+        }
+      `}
+      </style>
+      <div class="example example--themed-form-fields">
+        <Radio
+          label="This field is optional"
+          onChange={(e) => setFruit(e.target.value)}
+          options={options}
+          value={fruit}
+        />
+        <Radio
+          label="This field is optional but looks like required"
+          onChange={(e) => setFruit(e.target.value)}
+          options={options}
+          value={fruit}
+          renderAsRequired
+        />
+      </div>
+    </React.Fragment>
+  );
+})
+```
+
+It renders the field as if it was required, but doesn't add the `required`
+attribute to the actual input.
+
 ### Disabled State
 
 It's possible to disable just some options or the whole set.

diff --git a/src/components/Radio/Radio.jsx b/src/components/Radio/Radio.jsx
@@ -16,6 +16,7 @@ export const Radio = ({
   label,
   layout,
   options,
+  renderAsRequired,
   required,
   validationState,
   validationText,
@@ -33,7 +34,7 @@ export const Radio = ({
           ? styles.isRootLayoutHorizontal
           : styles.isRootLayoutVertical,
         disabled && styles.isRootDisabled,
-        required && styles.isRootRequired,
+        (renderAsRequired || required) && styles.isRootRequired,
         getRootValidationStateClassName(validationState, styles),
       )}
       disabled={disabled}
@@ -116,6 +117,7 @@ Radio.defaultProps = {
   id: undefined,
   isLabelVisible: true,
   layout: 'vertical',
+  renderAsRequired: false,
   required: false,
   validationState: null,
   validationText: null,
@@ -181,7 +183,11 @@ Radio.propTypes = {
     ]),
   })).isRequired,
   /**
-   * If `true`, the input will be required.
+   * If `true`, the input will be rendered as if it was required.
+   */
+  renderAsRequired: PropTypes.bool,
+  /**
+   * If `true`, the input will be made and rendered as required, regardless of the `renderAsRequired` prop.
    */
   required: PropTypes.bool,
   /**

diff --git a/src/components/Radio/Radio.module.scss b/src/components/Radio/Radio.module.scss
@@ -52,6 +52,10 @@
         @include foundation.label-required();
     }
 
+    .isRootRequired .optionLabel {
+        @include foundation.label-required($show-require-sign: false);
+    }
+
     // States
     .isRootStateInvalid {
         @include variants.validation(invalid);

diff --git a/src/components/Radio/__tests__/Radio.test.jsx b/src/components/Radio/__tests__/Radio.test.jsx
@@ -10,6 +10,7 @@ import { formLayoutProviderTest } from '../../../../tests/providerTests/formLayo
 import { isLabelVisibleTest } from '../../../../tests/propTests/isLabelVisibleTest';
 import { labelPropTest } from '../../../../tests/propTests/labelPropTest';
 import { layoutPropTest } from '../../../../tests/propTests/layoutPropTest';
+import { renderAsRequiredPropTest } from '../../../../tests/propTests/renderAsRequiredPropTest';
 import { requiredPropTest } from '../../../../tests/propTests/requiredPropTest';
 import { validationStatePropTest } from '../../../../tests/propTests/validationStatePropTest';
 import { validationTextPropTest } from '../../../../tests/propTests/validationTextPropTest';
@@ -83,6 +84,7 @@ describe('rendering', () => {
         expect(within(rootElement).getByLabelText('option 2')).toBeDisabled();
       },
     ],
+    ...renderAsRequiredPropTest,
     ...requiredPropTest,
     ...validationStatePropTest,
     ...validationTextPropTest,