@devseed-ui/theme-provider

@devseed-ui/theme-provider

  import {
    // Theme
    DevseedUiThemeProvider,
    GlobalStyles,
    createUITheme,
    theme,
    themeVal,
    createColorPalette,

    // Stylizing function
    stylizeFunction,

    // Conversions and math
    unitify,
    rem,
    px,
    val2px,
    val2rem,
    multiply,
    divide,
    add,
    subtract,
    min,
    max,

    // Global spacing and RGBA
    glsp,
    rgba,

    // Media queries
    media,

    // Style helpers
    antialiased,
    visuallyHidden,
    listReset,
    truncated,
    visuallyDisabled,
    disabled,
    unscrollableY,
    unscrollableX
  } from '@devseed-ui/theme-provider';

See the API reference for a description of each export.

Devseed-ui Theme Provider

How theming works with the ui-library

The components of the devseed-ui library require settings to be defined through a theme using specific variables.
The theme-provider contains the base provider with the ui-library's default theme. This can be used directly, or overridden by the user.

  import { DevseedUiThemeProvider } from '@devseed-ui/theme-provider';

The DevseedUiThemeProvider should wrap the whole application so that all components can get the correct variables from the theme.
This will apply the default ui-library theme and some global styles to normalize presentation across browsers.

  ...
  render (
    <DevseedUiThemeProvider>
      {components...}
    <DevseedUiThemeProvider
  )

It is also possible to provide a custom theme to DevseedUiThemeProvider using the theme prop.
It is important that the custom theme contains a value for all variables in the theme.

  const myCustomTheme = {
    ...
  };

  ...
  render (
    <DevseedUiThemeProvider theme={myCustomTheme}>
      {components...}
    <DevseedUiThemeProvider
  )

The best way to provide a new theme is to use the createUITheme helper and override the base theme variables, while also being able to add new variables. This helper will ensure that defaults are set when no custom values are provided. Check (./src/theme.d.ts)[theme.d.ts] for a list of all theme properties.

  const myCustomTheme = createUITheme({
    color: {
      base: '#F00',
      // This is a custom color.
      infographicColor: '#FF0'
    }
  });

  ...
  render (
    <DevseedUiThemeProvider theme={myCustomTheme}>
      {components...}
    <DevseedUiThemeProvider
  )

Theme

Check theme.d.ts for the default ui-library theme values.

API Documentation

Theme

Utilities directly related with the theme.

• DevseedUiThemeProvider [React Component]
  • Theme provider for the ui-library. Supports a custom theme through a theme prop. See How theming works with the ui-library.
• GlobalStyles [React Component]
  • Global styled applied by the ui-library. It is included in the DevseedUiThemeProvider, so this is not used often.
• createUITheme(definition) [function]
  • Creates a UI theme by combining the provided options with the default ones.
• theme [object]
  • Default ui-library theme.
• themeVal(path) [function]
  • Function to be used with styled-components to get a value from the theme.

    const Msg = styled.p`
      color: ${themeVal('color.primary')};
    `;
  

• createColorPalette(name, baseColor) [function]
  • Function to create a color palette base off of the provided base color including lightened/darkened/transparent versions of that color.

Stylizing function

• stylizeFunction(function) [function]
  • Utility to convert functions so that they can be used with styled-components.
  • For example, the tint function provided by Polished has the following signature:

    tint(percentage: (number | string), color: string): string
  

  • This means that to use a color from the theme while in a styled-component block we'd need:

    const Msg = styled.p`
      color: ${({ theme }) => tint('50%', theme.color.primary)};
    `;
  

  • By "stylizing" the function, we can use it directly and in conjunction with themeVal

    const _tint = stylizeFunction(tint)
    const Msg = styled.p`
      color: ${tint('50%', themeVal('color.primary'))};
    `;
  

Conversions and Math

Utilities to be used with styled-components to do conversions and math operations.
All the functions can be used directly with styled-components and themeVal, for example:

  const Msg = styled.p`
    padding: ${multiply(themeVal('layout.border'), 3)}; // 3px
  `;

• unitify(unit) [function]
  • Return a function that appends the unit to the value.

    const percent = unitify('%');
    percent(10) // -> 10%
  

• rem(value) [function]
  • Appends rem to the give value.
• px(value) [function]
  • Appends rem to the give value.
• val2px(value) [function]
  • Convert the given value to pixels using the base size defined in the theme (theme.type.base.root).
• val2rem(value) [function]
  • Convert the given value to rem using the base size defined in the theme (theme.type.base.root).
• multiply [function]
  • Multiplies two values keeping the unit of the first one. Eg: 2rem * 2 = 4rem | 2 * 2rem = 4
• divide [function]
  • Divides two values keeping the unit of the first one. Eg: 2rem / 2 = 1rem | 2 / 2rem = 1
• add [function]
  • Adds two values keeping the unit of the first one. Eg: 2rem + 2 = 4rem | 2 + 2rem = 4
• subtract [function]
  • Subtracts two values keeping the unit of the first one. Eg: 4rem - 2 = 2rem | 4 - 2rem = 2
• min [function]
  • Returns the minimum of two values. Units are discarded when doing the comparison, but the value is returned with a unit if both arguments has the same one or if only one has it. Eg: 10px, 15 = 10 | 4rem, 5px = 4
• max [function]
  • Returns the maximun of two values. Units are discarded when doing the comparison, but the value is returned with a unit if both arguments has the same one or if only one has it. Eg: 10px, 15 = 15 | 4rem, 5px = 5

Global Spacing and RGBA

• glsp(...args) [function]

  • Almost all spacing in the library (margin, padding) is defined as multiples or fractions of the layout.space. This allows all the components to gracefully scale based on a single setting.
  • This function accepts a variable number of arguments in the form of a multiplier.

    padding: ${glsp(2, 1 / 2)};    // 2rem 0.5rem
    padding: ${glsp(2, 0.5)};      // 2rem 0.5rem
    padding: ${glsp()};            // 1rem
  

  • If no arguments are provided it is assumed a single value of 1.

• rgba(color, value) [function]

  • Applies the given transparency value to the color. This function is the same as the rgba exported by the polished module, but modified to work with styled-components. See Stylizing function.

    const Msg = styled.p`
      color: ${rgba(themeVal('color.primary'), 0.5)};
    `;
  

Media queries

The media queries will be available through the media object as Up, Only, and Down variations of each range defined on the theme.
For example, with the range (medium: [768, 991]):

• mediumUp will be triggered from 768px;
• mediumOnly will stay active between 768px and 991px;
• mediumDown while the viewport is below or at 991px.

All available options are:

media.xsmallOnly
media.xsmallDown

media.smallUp
media.smallOnly
media.smallDown

media.mediumUp
media.mediumOnly
media.mediumDown

media.largeUp
media.largeOnly
media.largeDown

media.xlargeUp
media.xlargeOnly

These can be used directly on styled-components using template literals:

  const Msg = styled.p`
    color: red;

    ${media.mediumUp`
      color: blue;
    `}

    ${media.largeUp`
      color: green;
    `}
  `;

Helpers

The helpers are to be used within a styled-component and return useful snippets of code.

• antialiased [function]
  • Applies anti-aliasing to font rendering, making the text more readable and pleasing to the eye. Webkit and mozilla specific.
• visuallyHidden [function]
  • Hides elements visually, but preserving its accessibility to screen readers or crawlers. Useful for semantic solutions.
• listReset [function]
  • Removes default list (ul and ol) styling. Say goodbye to default padding, margin, and bullets/numbers.
• truncated [function]
  • Truncates a text string and applies ellipsis. Requires a declared width value.
• disabled [function]
  • Applies disabled styles to an element, and disabled pointer events.
• visuallyDisabled [function]
  • The same behavior as disabled, but the pointer events remain active. This is useful when, for example, paired with a tooltip that needs the hover event to fire.
• unscrollableY [function]
  • Constrains element content to its declared height, preventing vertical scrolling.
• unscrollableX [function]
  • Constrains element content to its declared width, preventing horizontal scrolling.

Use directly in a styled-component:

  const Msg = styled.p`
    ${antialiased()}
  `;