# Language Tutorial
This page contains a tutorial covering the essential parts of the hop language.
All of the code examples on this page are interactive. You can click the **Open in
playground** buttons on the bottom of the code blocks to run the code in your
browser.
Let's get started!
## Views
Views are the entry points for a hop program.
Every view in a program compiles to a function that is callable from Rust.
The simplest possible program is one that declares a single view.
```hop
view Greeting(name: String) {
Hello {name}!
}
```
Any describable type in hop can be used as the type of a view parameter,
allowing you to pass data from the host program in a fully type-safe manner.
In Rust, we would render the `Greeting` view like this:
```rust
mod hop;
fn main() {
let view = hop::Greeting {
name: "World".to_string(),
};
println!("{}", view.render());
}
```
When compiling the view, hop will add the necessary boilerplate to turn
your view into a complete HTML document.
```html
Hello World!
```
Let's move on to the next topic, components!
## Components
Components are the building blocks of a hop program.
Components make it possible to construct composable user interfaces. This
concept might be familiar to you if you've ever tried React, Vue,
Blazor, Flutter or similar frameworks.
The syntax for declaring a component looks a lot like the syntax for declaring
a view. However, unlike views, components can be invoked in views and in
other components.
```hop
// The AlbumCard component renders an album with its cover art.
component AlbumCard(
cover: String,
title: String,
author: String,
year: Int,
) {
{title}
Released {year.to_string()} by {author}
}
// In the Main view we render three instances
// of the AlbumCard component.
view Main {
}
```
### Styling components
To style our components we'll use the CSS framework Tailwind.
hop has built-in support for Tailwind so we can get started by
just adding Tailwind classes directly to the `class` attribute of
HTML elements in the code.
If you've never used Tailwind before we recommend skimming [their introduction](https://tailwindcss.com/docs/styling-with-utility-classes)
before continuing.
Now, let's add some styling.
```hop
component AlbumCard(
cover: String,
title: String,
author: String,
year: Int,
) {
{title}
Released {year.to_string()} by {author}
}
view Main {
}
```
If you've seen Tailwind before the additions above will probably look mostly familiar to you.
One thing that might stick out is the use of the `join!` macro inside the `Main` view
containing the CSS classes broken up into separate strings.
The `join!` macro concatenates strings, adding a space between each string while filtering out empty strings.
In hop, it is idiomatic to use this macro to break up class strings.
This aids readability and allows for better diffs in version control systems.
The `join!` macro is evaluated at compile time and adds no runtime overhead so it is recommended to use it generously.
The hop formatter will also break up and format the strings for you automatically if you write
`join!("foo bar baz")`.
## Building flexible components
Designing flexible components that are easy to reuse across different contexts of a user interface is hard.
Just like in all software design, spending some time thinking about how components will be
used before establishing their API usually pays off in the long run.
### Modules and visibility
One of the most fundamental tools in software design is encapsulation, the ability
to decide whether code and data should be public or private in a given context.
In hop, any declaration (such as a component declaration or a type declaration)
can either be private to the file they are declared in, or public to the whole
program.
By default, all declarations are *private* and can only be used in the file
they are declared in. To make a declaration *public*, add the keyword `pub` to
the start of a declaration. When a declaration is made public, it can be
imported from another file using the `import` keyword.
::: code-group
```hop [main.hop]
import icons::DownloadIcon
import icons::GhostIcon
import icons::HeartIcon
view Main {
}
```
```hop [icons.hop]
pub component DownloadIcon {
}
pub component GhostIcon {
}
pub component HeartIcon {
}
```
:::
The ability to make components private makes it possible to break up complex
components into sub-components without changing the public interface that a file
exports.
Now, let's look in to component composition.
### Slots and composition
To make composition of components possible, hop allows for components to
declare a *slot* which allows the invoker to render markup inside the slot. The
parameter name of a slot must be declared as `slot` (lowercase) and its type
must be `Slot` (capitalized).
::: code-group
```hop [main.hop]
import icons::DownloadIcon
component Button(slot: Slot) {
}
view Main {
}
```
```hop [icons.hop]
pub component DownloadIcon {
}
```
:::
The fact that a component can have at most one slot might seem like a serious
limitation, but we can leverage the slot as a building block to create
complex structures. We will look into that now.
### Compound component pattern
The compound component pattern is, in some sense, a way to create a component
structure that can have multiple slots. In this pattern we create a hierarchy
of components that should be used together.
It is recommended to let all components that are part of the same hierarchy
share a prefix in their name. If it makes sense, let the name of the
outermost component be just the prefix.
::: code-group
```hop [main.hop]
import alert::Alert
import alert::AlertTitle
import alert::AlertDescription
import icons::CircleCheckIcon
view Main {
Upload successful
Your package has successfully been uploaded to the repository.
}
```
```hop [icons.hop]
pub component CircleCheckIcon(class: String = "") {
}
```
:::
### Component variant pattern
It is often useful to be able to define different variants of a component that
share a common base style.
In hop, the idiomatic way to achieve this is to declare the variants as an
enum, and then use `match` expressions to handle each case. The `match`
expression in hop is similar to the one in Rust. It is always exhaustive,
meaning that the compiler will tell you if you've forgot to handle a case.
::: code-group
```hop [main.hop]
import icons::DownloadIcon
enum ButtonSize {
Sm,
Default,
Lg,
}
component Button(
slot: Slot,
size: ButtonSize = ButtonSize::Default,
) {
}
view Main {
}
```
```hop [icons.hop]
pub component DownloadIcon {
}
```
:::
### Appending and overriding CSS classes
It can be useful to be able to override or
append to the default styles of a component. To achieve
this we can allow for extra classes to be sent in via
a parameter and added to the arguments of `join!`.
It is idiomatic to call the extra parameter `class` so that the attribute for a
component mirrors the attribute for an HTML element.
::: code-group
```hop [main.hop]
import icons::DownloadIcon
component Button(
slot: Slot,
class: String = "",
) {
}
view Main {
}
```
```hop [icons.hop]
pub component DownloadIcon {
}
```
:::
Note that we add a default value to the class parameter of the `Button`
component. This is necessary, since otherwise we would get a compile error if
we didn't provide a value for the `class` attribute when rendering `Button`. Default
values can be specified for component parameters, but not for view parameters.
::: info Advanced: Conflict resolution of Tailwind classes
If you are aware of the the intricacies of HTML/CSS you might be worried about
conflict resolution of Tailwind classes.
The fact that HTML puts no semantic meaning into the order in which classes appear inside
the `class` attribute has spawned various overhead inducing workarounds for component frameworks such as `twMerge` in React.
In hop, conflict resolution is handled automatically at compile time. Since hop is aware of
the semantics of Tailwind it evaluates the value of `class` attributes
and removes the classes that has overrides. The last CSS class of a conflict wins. Therefore it is important that the overrides appear
last inside the join macro or class string, i.e. `join!(..., overrides)`.
:::
### Advanced: Tagged element pattern
Sometimes a component needs to be able to be rendered as different HTML
elements (sometimes called *polymorphic components* in React). The typical
example of this is a `Button` component that needs to be rendered as an ``
element in some contexts and as a `