Semantic UI React components can have "shorthands". For example, Button
component has an icon
shorthand which value defines the icon that will be rendered.
jsx<Button icon='like' />
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:
jsx<> {/* 💡 'color' and 'name' will be used as <Icon /> element's props */} <Button content='Like' icon={{ color: 'red', name: 'like' }} /> {/* 💡 you can also add handlers and any DOM props to shorthands */} <Input action={{ icon: 'search', onClick: () => console.log('An action was clicked!'), }} actionPosition='left' placeholder='Search...' /> </>
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.
jsx<> <Button content='Like' icon='like' /> {/* 💡 has identical effect to the previous one */} <Button content='Like' icon={{ name: 'like' }} /> </>
This works because name
is the default prop of shorthand's <Icon />
element.
jsx<> <Modal trigger={<Button>Show</Button>} content='Content' /> {/* 💡 has identical effect to the previous one */} <Modal trigger={<Button>Show</Button>} content={{ content: 'Content' }} /> {/* ⛔ example below has broken styling, see section about React Element */} <Modal trigger={<Button>Show</Button>} content={<div>Content</div>} /> </>
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.
jsx<> {/* 💡 hides a toogle icon in `Dropdown` */} <Dropdown icon={null} /> <Dropdown icon={false} /> </>
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:
jsx<Button icon={<i className='my-icon' />} />
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:
jsx<Button icon={{ as: 'i', className: 'my-icon' }} />
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.
children
Providing function as a shorthand value is the most involving but, at the same time, the most powerful option for customizing component's shorthand. It should return React Element as a result or null
.
jsx<Button content='Like' icon={{ children: (Component, componentProps) => <Component {...componentProps} color='red' />, name: 'question', }} />
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:
jsx<Button content='Like' icon={{ children: (Component, componentProps) => <Label basic>+1</Label> }} />
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:
Thus, in its simplest form, it could be used the following way:
jsx<Button content='Like' icon={(Component, componentProps) => <Component {...componentProps} color='red' name='like' />} />