---
name: Common Types and Props
route: /common-types/
---

import { Playground } from 'docz';
import { Vertical } from '../..'; 
import * as demos from '../../demos'; 

<demos.Star/>

# Common Types

We present some common types referenced by the props.

## CSSLength
`type CSSLength = number | string`. 

Examples: 
* 5 (implies 5px)
* '5rem'

## CSSBox

Various versions of providing common shorthand properties.

```ts
export type CSSBox =
  /** top,right,left,bottom */
  | CSSLength
  /** [top & bottom, left & right] */
  | [CSSLength, CSSLength]
  /** [top,right,bottom,left] */
  | [CSSLength, CSSLength, CSSLength, CSSLength]
  /** Individual */
  | { top?: CSSLength, right?: CSSLength, bottom?: CSSLength, left?: CSSLength }
```

e.g. 
* `5` (means `5px` top,right,left,bottom).
* `['5rem','10px']` (means `5rem` top & bottom, `10px` left & right).
* `[10,5,'10rem', 15]` (means `10px` top, `5px` right, `10rem` bottom, `15px` left).
* `{right: 5}` (means `5px` right).

# Common Props

We have a common set of props that are supported by a number of components. These will be mentioned in the docs for the individual components as well. We present them below with a reference component.

## SpacingProp

```ts
export interface SpacingProp {
  /** Spacing between each child */
  spacing?: CSSLength,
}
```

* `spacing?: CSSLength` Controls spacing between children ([concepts covered in spacing principle][principle-spacing]). e.g. `spacing={10}` gives us:

<Playground>
  <Vertical spacing={10}>
    <div style={{backgroundColor: "lightskyblue"}}>Hello</div>
    <div style={{backgroundColor: "lightpink"}}>World</div>
    <div style={{backgroundColor: "darkorange"}}>Again</div>
  </Vertical>
</Playground>

## SizeProps

The explicit size props (`height,minHeight,maxHeight,width,minWidth,maxWidth`) allow for explicit size control as covered in the [sizing principle][principle-sizing] section.

## SizingProp

The implicit `sizing` prop is covered in the [sizing principle][principle-sizing] section.

## PaddingProp

```ts
/** 
 * Add support for padding
 */
export interface PaddingProp {
  padding?: CSSBox,
}
```

Allows you to specifiy padding as a [CSSBox](#cssbox). Using padding effectively is covered in the [spacing principle][principle-spacing] section.

## ScrollProp 

Contains `scroll?` member. Type definition and effective use is coverd in the [scrolling principle][principle-scrolling] section.

## StylesProp 

```ts
/** 
 * Support for mixing in TypeStyle NestedCSSProperties (style function arguments) 
 */
export interface StylesProp {
  styles?: (types.NestedCSSProperties | null | false)[];
}
```
`styles` props is an array that gets passed as arguments to the [`typestyle.style` function][typestyle-style].

E.g you can customize the hover color: 

<Playground>
  <Vertical height={100} styles={[
    {
      transition:'.3s', 
      backgroundColor: 'limegreen', 
      $nest:{
        '&:hover': {backgroundColor:'gold'}}
      }
  ]}/>  
</Playground>

> Any falsy array members will be safely ignored just like the `typestyle.style` function.

## StyleProp 

```ts
/** 
 * Support for React `style` property
 */
export interface StyleProp {
  style?: React.CSSProperties
}
```
Any custom react `style` you want to pass in. 

> Note that React `style` doesn't support things not supported by the html style attribute (e.g. media queries or pseudo elements). For that you can use [StylesProp](#stylesprop).

## ClassNameProp 
```ts
/** 
 * Support for React `className` property 
 */
export interface ClassNameProp { 
  className?: string
}
```
Allows you to add your own CSS classnames to the element.

## TagProps
```ts
/** 
 * Props supported by the underlying tag 
 */
export interface TagProps extends React.HTMLAttributes<HTMLDivElement> {
  tag?: string,
}
```
Gives you direct access to the underlying react tag for any customization you might want e.g. generate a `Vertical` as a `section` tag (instead of the default `div` tag) with an `onClick` handler:

<Playground>
  <Vertical 
    tag='section'
    onClick={() => alert('Nice you meet you ❤️')}
    height={100} style={{backgroundColor: 'limegreen'}}/>
</Playground>

Another example is a `Vertial` as a `ol`: 

<Playground>
  <Vertical tag='ol' spacing={5}>
    <li>Hello</li>
    <li>World,</li>
    <li>how</li>
    <li>are</li>
    <li>we?</li>
  </Vertical>
</Playground>

> If you need advanced customization you can use the `component` function to generate a `className` that you can use with any tag.

## BaseProps
A consistent set of customization options. Collects the following props into a common type: 

* `ScrollProp`: [Specify scrolling behaviours](#scrollprop).
* `PaddingProp`: [Specifies padding](#paddingprop).
* `SizeProps`: [Specify explicit size control](#sizeprops).
* `StylesProp`: [Allows you to use TypeStyle CSS mixins](#stylesprop). 
* `StyleProp`: [Allows you to specify React.CSSProperties](#styleprop).
* `ClassNameProp`: [Allows you to pass in CSS class names](#classnameprop).
* `TagProps`: [Allows all underlying tag properties and tag control](#tagprops).

[principle-spacing]:../principle-spacing/
[principle-sizing]:../principle-sizing/
[principle-scrolling]:../principle-scrolling/
[typestyle-style]:https://typestyle.github.io/#/core/style