Tenon-UI Documentation

Code on GitHub

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:

The name should be longer than 3 characters

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:

When does your pet eat? ( required )

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:

What colour is your pet? ( required )