Shorthand Props

Semantic UI React components can have "shorthands". For example, Button component has an icon shorthand which value defines the icon that will be rendered.

There are several forms of shorthand values that can be provided, but all of them share one common thing - each is eventually evaluated to React Element. Thus, you can think of shorthand values as a recipe to customize rendered React Element.

Each component's shorthand has an associated default element type. For example, by default, there is <Icon /> element rendered for Button's icon shorthand. It is possible to customize props of this default element by providing props object as shorthand value:

There is even shorter way to define default element's props - by using a primitive value. In that case provided shorthand value will be taken as a value for "default prop" of this element.

This works because name is the default prop of shorthand's <Icon /> element.

It is also possible to pass falsy values (false, null or undefined) - in that case there will be nothing rendered for the component's shorthand.

There are cases where it might be necessary to customize the element tree that will be rendered as a shorthand's value. Returning to Button example, we might want to render <i /> instead of default <Icon /> element. In that case, the necessary element might be directly provided as shorthand value:

There is a very important caveat here, though: whenever React Element is directly used as a shorthand value, all props that Semantic UI React has created for the shorthand's Component will be spread on the passed element. This means that the provided element should be able to handle props - while this requirement is satisfied for all SUIR components, you should be aware of that when either HTML or any third-party elements are provided.

Due to this limitation, you should strive to use other options for shorthand values whenever is possible - for instance, this is how the previous example can be rewritten:

However, there still might be cases where it would be impossible to use the object form of the shorthand value - for example, you might want to render some custom elements tree for the shorthand. In that case, function value should be used.

Providing function as a shorthand value is the most involving but, at the same time, the most powerful option for customizing component's shorthand. The only requirements for this function are:

it should finish synchronously
it should return React Element as a result

Thus, in its simplest form, it could be used the following way:

There is another use case when render function is very useful for - this is the case where custom element's tree should be rendered for the shorthand. As you might recall, there is a problem that might happen when React Element is provided directly as shorthand value - in that case, props are not propagated to rendered. In order to avoid that the following strategy should be considered:

Shorthand Props

Object as value

String as value

Disable shorthand's rendering

React Element as value

Function as value

Customizing rendered shorthand