A Beginner’s Guide to Using Semantic UI React

During winter break while attending Fullstack Academy I had the opportunity to take all that I had learned and create my first personal project. It is difficult to come up with clever project ideas but after a conversation with a friend who mentioned he uses an Excel spreadsheet to keep track of every book he has read, I knew what I wanted to try to create. It was to be a GoodReads-esque app that would visually keep track of all of the books in a user’s book collection, with personal ratings and all of the details about each book included. I knew that I wanted to aim for ease of use, in which using the app simply required typing a book title into a search bar, giving it a star rating out of five, clicking ’save’, and the app would do all of the rest.

After spending most of the first week of break getting the foundations set up: the api routes, the dummy data, the Redux store and reducers, the necessary components for React, I had one glaring issue in front of me. My personal project looked terrible. It had very little CSS, a very small search form, and mismatched book image sizes. Although I was new to the world of programming, I was familiar with the concepts of Bootstrap and knew there was a better way then single handedly writing out CSS code for every UI change that I wanted. Before immediately jumping into using Bootstrap, I did what I had done a lot in the past six weeks: google my issue. What popped up towards the top of the results was a link to the Semantic UI React docs, and the rest is history!

What I want to do in this blog post is share my learning process towards using Semantic UI React. I aim to go into describing how to read and understand the docs, getting Semantic set up for use with your app, and provide useful tips about features such as Grid and Forms that I personally felt were tricky to learn. My goal is to hopefully give you a better understanding of what makes Semantic UI React so useful when pairing up with React and even better, save you a few hours of frustration in trying to learn these methods all by yourself.

— Reading the Docs —

My first advice for learning how to use Semantic is, of course, to read the docs! When googling, make sure to fully write “Semantic UI React” so that you can get the docs specified to using React. Check that it says this at the top right corner:

Great, now here is the exciting part. If you scroll down on the left side, you can start to see all of the cool things that Semantic UI React can provide for your app. Some of the obvious ones are Buttons, Icons, and Images but then there are also features such as Feed, which would be perfect for a social app, or Step, which would go well with a E-Commerce app. For now, let’s click on Image. At the top of the page you are going to see a list of every possible prop that can be applied to customize your ‘Image’ and that may seem confusing right now. However, if you scroll down the page, you will see visual examples of various ‘Image’ elements, each using a different prop type. Even more helpful, click on ‘Edit Code’:

and below each example you will see the React code required to make it work:

Now you already have the bread and butter to understand how easy it is to use Semantic! As the example code shows, you will always import the specific element type from ‘semantic-ui-react’ within each component. In this case: import { Image } from ’semantic-ui-react’. Next it is usually as simple as following the example code and writing it into your own code. Where Semantic gets customizable is with what props you want to add to your element. In the example above, the image will have a rounded look because the ‘rounded’ props was passed in and will be sized proportionally to ‘medium’. Scrolling back to the top of the doc page, you now know that all of those prop names will provide unique characteristics to your element. Scroll down to find the visual example you want, click edit code to see React examples, and scroll up to see a list of every available prop!

— Installation —

Well now that you are familiar with understanding the documentation, you may ask how to get Semantic installed on your app. The quickest and easiest way to get started with Semantic is to npm install — save semantic-ui-react in your repository. Once it is installed, you will go to the ‘Usage’ link in the docs and copy this CDN link:

and add it within the head of your HTML file.

I want to pause here to point out that Semantic recommends installing Gulp, which is a build tool similar to Webpack, to be able to create custom CSS themes outside of the default style. Now, for my own project I did the CDN link option and after some trial and error and using Chrome Devtools, I was able to understand how to over-ride the default Semantic theme within a CSS file by adding ID selectors to the elements that I wanted to customize with my own colors and design choices. However, to learn more about designing themes and tweaking design within Semantic the proper way, then I recommend checking out this link: http://learnsemantic.com/.

Carrying on, once Semantic UI is installed and the CDN link is added, I recommend going into one of your components, import Button from ’semantic-ui-react’ and make a Button element render on the UI as a test to see if it is working. If it did, then congratulations you have successfully applied your first Semantic UI React element!

— Menus, Grids, Cards, Segments, Oh my —

Now that Semantic is ready for use, I want to jot out some quick helpful tips and then go into detail about particular Semantic features that I personally had some difficultly figuring out.

Let’s do quick tips first:

• ‘Menu’ can be used to easily create a navigation bar and footer, and can be turned into a sidebar as well by adding the ‘vertical’ prop.
• Using ‘Container’ with the ‘text’ and ‘textAlign’ prop added makes large paragraphs of text look neat and organized.
• Applying ‘Card.Group’ with the ‘itemsPerRow’ prop helps keep multiple images, items, avatars neatly lined up on a page. ‘Card’ by itself contains many props that can be useful for creating a visual template for profile information, social activity, and images with descriptions.
• Semantic comes with a wide variety of Icons that can provide the user with a quick visual cue of a button or form’s purpose. Adding a search icon is as easy as writing <Icon name=’search’ /> You can even nest Icons inside forms and buttons and other elements.
• ‘Item’ can be useful for grouping together a picture, a header, and inside content. For my personal project this was great for displaying a book cover, the title in bold and a summary, all bundled together.
• Spend time exploring every page of the docs because I keep finding new features that would fit well with my front-end ideas!

Next I want to dive into three areas that I felt took me longer to figure out.

- Grid -

The first is the Grid feature. Grid does essentially what you think it would do, separate your content into rows and columns. What may be tricky is understanding how Grid.Row and Grid.Columns will format your content into sections that you want. Here are a few rules of thumb with code examples that may help with understanding how Grid works.

<Grid>
  <Grid.Column>
    <Image src=“largePicture.jpg”>
    <Image src=“largePicture.jpg”>
    <Image src=“largePicture.jpg”>
    <Image src=“largePicture.jpg”>
  </Grid.Column>
</Grid>

You do not need to initially specify rows. If a <Grid.Column> is a direct child of <Grid>, like the code above, then Semantic will automatically wrap content into a new row if the column width is filled. Although the above code does not show it, imagine that the large pictures are automatically wrapped into two rows of two due to width constraints.

<Grid columns={2}>
  <Grid.Column></Grid.Column>
  <Grid.Column></Grid.Column>
  <Grid.Column></Grid.Column>
  <Grid.Column></Grid.Column>
</Grid>

On the other hand, by specifying within the parent <Grid> how many columns you want, Grid will divide the columns by that number and any extra columns will be automatically wrapped to a new row. If the above example contained small pictures instead of large ones, it would still wrap into two rows with two pictures each.

<Grid>
  <Grid.Column width={2}></Grid.Column>
  <Grid.Column width={8}></Grid.Column>
  <Grid.Column width={6}></Grid.Column>
</Grid>

Specifying specific widths is an option too. Semantic UI goes by a default total width of 16 so it is important to divide your widths by that number. The above example would have three columns within one row, each a different width.

<Grid columns=‘equal’>
  <Grid.Row>
    <Grid.Column></Grid.Column>
    <Grid.Column></Grid.Column>
    <Grid.Column></Grid.Column>
  </Grid.Row>
  <Grid.Row>
    <Grid.Column></Grid.Column>
  </Grid.Row>
</Grid>

To manually break up your columns into new rows, you guessed it: Wrap it with a <Grid.Row>. By adding the “columns=‘equal’ prop, the columns will automatically try to fit evenly inside its row.

I also recommend taking a look at the “verticalAlign”, “centered”, and “container” props for Grid to help with your perfecting your layout design. Finally, know that Grid uses Flexbox under the hood so if you are familiar with Flexbox then now you know that Grid is essentially the same thing!

-Local state and value -

The next area that I want to focus on relates to using a component’s state to store values from Semantic UI elements that take in input. I feel that a brief logic explanation can go a long way in understanding how features such as Forms and Search can be easily implemented within a React component. Below is example code for a Form:

import React, { Component } from ‘react’;
import { Form } from ‘semantic-ui-react’;
import { connect } from ‘react-redux’;
import { exampleFormDispatcher } from ‘../store’;
class exampleComponent extends Component {
  constructor() {
    super()
    this.state = {
      name: ‘’,
      email: ‘’
    }
  this.handleChange = this.handleChange.bind(this)
  this.handleSubmit = this.handleSubmit.bind(this)
  }
  handleChange = (e, { name, value }) => 
    this.setState({ [name]:   value })
  handleSubmit = () => {
    const { name, email } = this.state
    this.props.exampleFormDispatcher(name, email)
  }
  render () {
   const {name, email} = this.props;
   return (
    <Form onSubmit={this.handleSubmit}>
      <Form.Group>
        <Form.Input placeholder=’Name’ name=’name’ value={name}         
           onChange={this.handleChange} />
        <Form.Input placeholder=’Email’ name=’email’ value={email}   
           onChange={this.handleChange} />
        <Form.Button content=’Submit’ />
      </Form.Group>
    </Form>
    )
  }
}
/****** Container ******/
const mapDispatchToProps = { exampleFormDispatcher }
export default class(null, mapDispatchToProps)(exampleComponent)

As you can see, this.state holds two keys: name and email, and each is currently assigned with an empty string. Inside the Form.Group, each Input has a name that matches it’s purpose and also matches a key in the state (i.e. ‘email’ === this.state.email). The value of each Input is also the value from the state. Each Input can update this.state with an onChange method, such as the above example’s this.handleChange method.

What Semantic does different from regular React forms is that it passes into its onChange methods two parameters: e and data. The first parameter is the event, which is normally used to find the event.target.name/value to update the state. However with Semantic UI elements, what is important is the second parameter. This parameter passes an object that holds data from the Input that is being changed. This makes it very easy to destructure the prop types that you want, such as the above case: name and value (i.e. handleChange = (e, { name, value }) ) and use them to update the state. As you can see in the code, if a user were to be typing in the email Input, the {name} data in this.handleChange will equal ‘email’, because that Input’s name equals ‘email’, and this.handleChange’s {value} will equal the text that is being typed into the email input form. Take a second to let that digest.

With each input change, this.handleChange is instantly updating the corresponding the state value and the state value is updating the value of the form! It’s an instant cycle of updates that can then be captured in a submitHandler that perhaps uses a Redux thunk or action dispatcher to update the Redux store. Understanding that the second parameter is where you can access data from onChange events is very important when using not only Forms but also Search, Dropdown, and more.

-Conclusion -

In conclusion, I hope that this blog post will be useful for those new to Semantic UI React. Truthfully, Semantic’s documentation is really great and the best advice I can give is to just spend time looking at example code and looking at how specific props affect the element. Semantic UI comes with a lot of neat features and makes building up the front-end design much easier than trying to do it all on your own. I think that installing it by using the CDN link in the HTML is perfect for small to medium personal projects. Even though I feel more comfortable with using Semantic UI React after just one project, it is obvious that I have much more to learn and that there is plenty of untapped potential to be used for front end design options. I would like to look into Gulp or Webpack configurations in a later project and get to really understand how to customize the details of Semantic UI elements properly. Hopefully it will result in a future blog post to share with those interested in learning more about it as well. For now, I want to thank you for reading through my post. I hope that you found a few tips useful and that perhaps this saved you an hour or two of learning when you decide to check out Semantic UI React yourself. Thank you.