GymnastProvider

<GymnastProvider /> is an optional, pass-through component that allows customizing gymnast's default values.

API

All parameters are optional

Parameter	Type	Default
base	Number	8
columns	Number	12
displayAliases	Object	See displayAliases section
gutter	Number	3
maxPageWidth	Number	153
minPageWidth	Number	50
pageMargin	Number / String / Object	{ small: 1, medium: 6, large: 6 }
spacingAliases	Number / String / Object	See spacingAliases section
verticalGutter	Number	3

Any property set through <ConfigProvider /> overrides the matching default value entirely. i.e. properties override, they are not merged with default values.

<GymnastProvider /> can take any of the following properties:

base

base is the core unit used by gymnast. It defaults to 8. All values provided to gymnast are treated as multiples of base. e.g. if we wanted to set base to 10px we would do:

<ConfigProvider base={10} />

Now if we define <Grid margin={2} /> it becomes something like:

.grid {
  margin: calc(10px * 2);
}

columns

columns specifies the number of columns available on the grid layout. It defaults to 12.

You can use it to change the default as follows:

<ConfigProvider columns={2}>
  <Grid size={2} />
  <Grid size={2} />
</ConfigProvider>

this will display each <Grid /> in a new row. If instead, we set it to 4 columns:

<ConfigProvider columns={4}>
  <Grid size={2} />
  <Grid size={2} />
</ConfigProvider>

These <Grid />s will be displayed side by side since now 2 size 2 <Grid />s can fit in 4 columns.

displayAliases

displayAliases is how gymnast enables responsive layouts. It's an object that contains aliases as keys and an object defining the relevant media queries as value.

For instance, the object below would define an alias named "smallLandscape" that applies when the device is in landscape mode and the screen width is 600px or below

{
  "smallLandscape": {
    "maxWidth": "600px",
    "orientation": "landscape"
  },
  // ...
}

The following keys are supported: minWidth, maxWidth, minHeight, maxHeight, aspectRatio and orientation, and the following defaults are provided:

Alias	Value
small	{ "maxWidth": "599px" }
medium	{ "minWidth": "600px", "maxWidth": "899px" }
large	{ "minWidth": "900px" }

These values can be consumed in 2 ways: through the show property on <Grid /> and <Layout /> components and using the object format for properties that allow it (e.g. <Grid size={{ small: 4, large: 6 }} />).

By default components are always rendered but you can also hide or show them based on screen width media queries. For instance:

  <Grid show="large">Only visible on large screen widths</Grid>
  <Grid show={['small', 'medium']}>Only visible on small and medium screen widths</Grid>
  <Grid>Always visible</Grid>

And customizing the aliases:

<ConfigProvider displayAliases={{
  XL: { minWidth: '801px' },
  L: { minWidth: '601px', maxWidth: '800px' },
  M: { maxWidth: '600px' }
}} base={24}>
  <Grid show="XL">Only visible on XL screen widths</Grid>
  <Grid show={['L', 'M']}>Only visible on L and M screen widths</Grid>
  <Grid>Always visible</Grid>
</ConfigProvider>

See the Responsive Grids section for additional details.

gutter

gutter indicates the separation to be used between columns when using the component. You can also specify verticalGutter if it differs from the horizontal one but verticalGutter will default to gutter which defaults to 3 times base.

So if base is 8px and gutter is 3, gutters are rendered as 24px of separation between columns (3 * 8px = 24px).

maxPageWidth

maxPageWidth determines the max width of the page. It defaults to 153 times the base size (153 * 8px = 1224px). If you want to ensure the page is centered after this size is exceeded, you can use the component.

Note that this behavior is enforced by the component not the .

minPageWidth

minPageWidth ensures the page width is at least that size. It defaults to 50 times the base size (50 * 8px = 400px). This is particularly important for column based layouts where, even after accounting for responsive, small layouts, a screen may be too narrow to properly display the content.

This behavior is also enforced by the component not the .

pageMargin

pageMargin is an object where the keys indicate the displayAlias to use and the value is the page margin (in multiples of base) for that resolution.

For instance, if base is 8px and we wanted 8px margin on small size but a 16px (8px * 2) one for medium and large we would define it as:

<ConfigProvider
  pageMargin={{
    "small": 1,
    "medium": 2,
    "large": 2
  }}
/>

Page margins are easier to see using the component, where they are highlighted in yellow.

spacingAliases

spacingAliases allow defining margin and padding values as variables. With them, you can specify margin="M" instead of margin={2}. This enables a single language with design that helps prevent pixel pushing by abstracting pixel values to a spacing system and limiting valid values.

spacingAliases are defined as a key-value object where the aliases are keys and the values are base multipliers. In other words, values are multiples of the base size. E.g. if base is 8 and alias M is set to 2, then M will equal 8 * 2 = 16px.

spacingAliases can be used on all spacing props.

The following defaults are provided:

Alias	Value
XS	0.5
S	1
M	2
L	3
XL	4
2XL	6

Half sizes for values greater than XS are included as well

Alias	Value
S/2	0.5
M/2	1
L/2	1.5
XL/2	2
2XL/2	3

If you want to customize these defaults, you could define:

<ConfigProvider spacingAliases={{ Big: 1.5, Small: 0.5, Regular: 1 }} base={24}>
  <Grid margin="GreatSize" />
  <Grid padding={['Big', 'Small']} />
</ConfigProvider>

verticalGutter

verticalGutter indicates the separation to be used between multiple rows when using the component. If not set it will default to gutter which defaults to 3 times base.

So if base is 8px and verticalGutter is 3, vertical gutters are rendered as 24px of separation between rows (3 * 8px = 24px).

React 15.5 limitations

Because <ConfigProvider /> renders its children directly, you must use React 16 or above if you want to return more than one element.

For instance, the following will not work using React 15.5 or below:

<ConfigProvider base={12}>
  <Grid size={2} />
  <Grid size={10} />
</ConfigProvider>

But the following cases would:

<ConfigProvider base={12}>
  <div>
    <Grid size={2} />
    <Grid size={10} />
  </div>
</ConfigProvider>

<ConfigProvider base={12}>
  <Grid size={2} />
</ConfigProvider>