Component model

In this section you can find detailed information about how to handle components specifities such as state, styling, composition and internationalization.

State

All Shoreline components are Controlled. This means that they are responsible for managing their own state and exposing it to the parent component. This way, the parent component can control the state if necessary.

You can check the State Management section to understand how it works and how to use it.

Styling

The way we style component in Shoreline is equal the way we recommend our users to style their components. The only difference is that we use use Sass to apply css. The theme and the styles are defined within the shoreline package, you can check it here

Go for the Styling section to get a detailed information and understand how styling works in Shoreline.

Composition

Composition is often useful for easily extending behavior. Shoreline relies on the children’s property for this task. Composable components accept the asChild boolean property. When true, the component will not render its default DOM element, cloning the props to the first child instead.

You can check the Composition section to understand how it works and how to use it.

You must use the Compose component in order to implement composition within Shoreline. This component is responsible for render the children and pass the props to them.

import { Compose } from '@vtex/shoreline';
 
export function ComposableButton(props) {
  const { asChild, ...restProps } = props;
  const Composition = asChild ? Compose : 'button';
 
  return (
    <Composition {...restProps}>
      {children}
    </Composition>
  );
}

Internationalization

We have internal translations to help our users by previously defining common messages and letting them use the messages. This way, we can ensure that the messages are consistent across the apps.

You must follow 3 steps in order to implement internationalization within Shoreline:

// messages/en.json file
{
  "search-label": "Search"
}

import { createMessageHook } from '@vtex/shoreline'
 
const useMessage = createMessageHook(messages)
 
function Search(props) {
  const getMessage = useMessage()
 
  return <input placeholder={getMessage('search-label')} {...props}/>
}

import { createMessageHook } from '@vtex/shoreline'
 
const useMessage = createMessageHook(messages)
 
function Search(props) {
  const { messages } = props
  const getMessage = useMessage(messages)
 
  return <input placeholder={getMessage('search-label')} {...props}/>
}
 
interface SearchOptions {
  /**
   * Search internal messages
   */
  messages?: SearchMessages
}
 
export type SearchProps = SearchOptions & ComponentPropsWithoutRef<'input'>
 
type SearchMessages = {
  'search-label'?: string
}