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.

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.

Object as value

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...'
  />
</>

String as 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.

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>} />
</>

Disable shorthand's rendering

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} />
</>

React Element as value

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' />} />
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:

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.

Render props via 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',
  }}
/>

Customizing rendered shorthand

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> }}
/>

Function as value (deprecated)

This usage is deprecated and will be removed in v3, please use render props instead.

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:

jsx
<Button
  content='Like'
  icon={(Component, componentProps) => <Component {...componentProps} color='red' name='like' />}
/>
Blazing deployments by Vercel.