The Tenon-UI view components
Usage
All view components can be used in one of two ways.
The component prop
Here is an example of using the Input component by using the component prop of the controller.
Note that the labelText prop for the view component is added to the controller component which will then pass these props through to the view component. This ONLY happens when you use the component prop.
This method is recommended when using a view component, even if you have created it yourself, and will be used further on this page.
The children render prop
You can still use the view components in the children render prop of the controllers.
Here is an example of using the Input component to show how all view components can be used inside the children render prop of each controller:
It is VERY important to spread the props object from the render function of the controller onto the view component. This passes the required props into our view components. The same props you would otherwise use when creating your own views.
Common component props
labelText
Required when present. Not used for RadioGroup and CheckboxGroup.
Every form control needs a text label. With this prop you provide the text that will be rendered inside the <label> element.
labelProps
Not used for RadioGroup and CheckboxGroup.
This is an optional object that can be used to override or amend the props that passed to the <label> element.
For example, if you want to add a specific className to the <label> of the <textarea> element you can do this:
contentHintText
Every form control can also have content hint text. This is text that describes what should be entered into the control. For example, an input that requires at least five characters.
Note: The <input> placeholder attribute is often used for this, but this is wrong. The placeholder should never be used for this function as it causes difficulty for many users out there.
Specify a content hint text as follows:
Content hints are rendered as follows:
Should you open the browser's HTML inspector, you will find that the content hint container is linked to the <input> element with the aria-describedby property. This is very important for screen readers.
requiredText
With this prop you can set the text that displays next to the <label> text for required fields.
If you do not set this, a * will be shown for required fields as this is a standard pattern on the web. If you use this, please put a legend somewhere on your form that indicates that a * denotes a required field.
You don't have to do any more than that as Tenon-UI already marks required fields in a way that screen readers can interpret.
Tenon-UI specific props
Should you look at the code for the view components, you will see that it also expects a number of other props. These are the props that is provided by the smart controller components as seen in the examples above.
Please do not provide these props yourself as this will most probably break the functionality of the component.
Other props
Not relevant for RadioGroup and CheckboxGroup.
Any other props given to these components will be passed onto the relevant functional HTML element.
Refs
In some case you may want to create a React ref to the form controls.
In accessible applications, this is mostly done in cases where you want to set focus to a specific element.
Each view component forwards the ref to the the correct element so that you can easily set focus when required:
Note: If you want to create a ref to any of the view components, you HAVE to use the children render prop version. Otherwise you will get a reference to the instance of the controller component class!
The Input component
As already illustrated above, the input component is used as:
Using this inside the Form component gives:
Overriding the input type
By default an <input type="text"> will be rendered. But this can also be overridden.
The TextInputController will also play nice with other types.
Override it like this:
The TextArea component
Using this inside the Form component gives:
The Select component
The Select component needs options and those are provided as children of the component in the same way they would be coded in normal HTML.
As we suggest passing it into the component prop of the SelectController, you can now code the <option> elements as children of the controller as they are passed as children to the component injected into the component prop.
Using this inside the Form component gives:
The Checkbox component
The Checkbox component should be used to render single checkboxes. Please do NOT use this to create groups of checkboxes related to the same choice, rather use the CheckboxGroup.
Also note here how easy it is to create ad-hoc validations with Tenon-UI.
Using this inside the Form component gives:
The CheckboxGroup component
Use this component if you want to render a group of related checkboxes.
Aside from the standard props for Tenon-UI view components, this component also accepts the following.
legend
This prop is required.
Use this to set the <legend> for the group of checkboxes. This acts as a grouping label.
options
This prop is required.
Use this to provide an options object to the component. This will be used to automatically render a group of checkboxes based on this object. The object is an indexer object:
When used, the property names will become the values of the checkboxes while the property values will become the labels of the checkboxes.
Usage
Using this inside the Form component gives:
If you try this example, you will notice that the CheckboxGroupController passes an array of values to the Form component. In this way the CheckboxGroupController differ from all other controllers in Tenon-UI.
The RadioGroup component
Use this component if you want to render a group of radio buttons.
Aside from the standard props for Tenon-UI view components, this component also accepts the following.
legend
This prop is required.
Use this to set the <legend> for the group of radio buttons. This acts as a grouping label.
options
This prop is required.
Use this to provide an options object to the component. This will be used to automatically render a group of radio buttons based on this object. The object is an indexer object:
When used, the property names will become the values of the radio buttons while the property values will become the labels of the radio buttons.
Usage
Using this inside the Form component gives: