React reusable component example

[just214]

I created an example reusable React component using Twind and thought I’d share the link for anyone interested. If you have any thoughts on how to improve it, please share!

CodeSandbox Link: https://codesandbox.io/s/twind-react-typescript-wmm6t

• Written in React/TypeScript
• Styled with Twind
• Exported type definitions with JSDoc comments for easy Storybook integration
• Uses forward ref to allow for setting ref on instance
• Allows for className overriding via the override variant
• Example usage in App component
• Logged classNames for convenience

[sastan]

That looks just amazing!

I see you used a lot of twind features. Really great.

Things i really like:

• bg(${variantColor}(600 700(hover:& focus:&))) – that's something 👍
• using override for customization
• using props for dynamic directive names
• using grouping
• logging the class names

Just a few things if you are open for it:

• the override variant is included in twind since v0.10.0 – no need to define in setup

The next two are just to show what may be used for optimal performance.

• the sizeClassNames can be optimized to be inline function which can be cached

    const sizeClassNames = {
      sm: ({ tw }) => tw`text-xs py-1`,
      md: ({ tw }) => tw`text-sm py-1`,
      lg: ({ tw }) => tw`text-lg py-2`,
      xl: ({ tw }) => tw`text-2xl py-2`
    };

• you could inline bgClassNames into classNames which would prevent parsing it every time

      // Get the text size based on the "size" prop
      const buttonSizeClassNames = sizeClassNames[size];
      // Create the full className, passing the instance-level classNames to the "override" variant
      const classNames = tw`
      w(full md:auto) 
      bg(${variantColor}(600 700(hover:& focus:&)))
      ${buttonSizeClassNames}
      text(sm white uppercase) 
      px-4 
      rounded-${round ? "full" : "lg"} 
      border-none 
      transition-colors 
      duration-300
      override:(${className})
    `;

This is really good. Thanks for sharing.

Would you be interested in testing/trying the twind/styled PR?

[sastan]

After seeing this application we may need to support some kind of comment syntax with template literals...

[just214]

Thanks for all the feedback and happy to share! I really enjoy using Twind.

As far as inlining the bgClassNames…I originally tried that and ran into these errors: Error: [UNKNOWN_THEME_VALUE] {"key":"backgroundColor.600”}. I just tried again and am seeing the same thing.

I’ve made the other changes that you recommended. I appreciate the tip about caching with the inline functions 👍.

And, yes, I’d be happy to try out the styled API. I skimmed through the PR the other day and I’ve actually been looking forward to trying it! And sure, you are welcome to add this example to the “Show & Tell”! And yes, comments would also be great!

[sastan]

You're right inline bgClassNames does not work. I think that has to do with some optimization we do for the template literal case. I'll look into it.

[just214]

Happy New Year! 🎉

I’ve added some new components to this demo, some using the styled api. I’ll continue to improve on this, and as always, I am open to feedback!

CodeSandbox Link: https://codesandbox.io/s/twind-react-typescript-wmm6t

[slapner]

is the styled api experimental? I don't have that import in my twind version 0.12.0

[sastan]

Yes. We are working on that: #7

[sastan]

That is awesome!!!! Great job. You have use so many features of twind – this is a really good showcase.

Would you be willing to add that to the tw-in-js org? I have created a repo (https://github.com/tw-in-js/example-react-typescript) and gave you maintain access.

I'd love for more people to see that and use it a reference for the things that can be done with twind.

[just214]

Thanks! I’ve made some changes to the project and pushed the updated version to https://github.com/tw-in-js/example-react-typescript.

The bigger changes include:

• Move from Parcel to Snowpack
• Add Storybook integration and examples
• Setup tests and ESLint

[sastan]

You are doing a really great job there! We should find a way to present these examples on the website or the docs.

[just214]

I created a fork of the React/TypeScript CodeSandbox demo using the apply function:

https://codesandbox.io/s/twind-apply-react-typescript-73pm9

The apply API feels much nicer and intuitive when composing styles. Also, refactoring from inline directives and/or the override variant was a breeze. My plan is to update the example on GitHub to use a combination of apply and styled once the styled API is finalized and released. As always, any feedback is welcomed.

[sastan]

I really like it! Maybe we can link this in the react doc section: https://twind.dev/docs/handbook/recipes/use-with/react.html

[sastan]

Hey @gojutin,

I have taken a closer look at your sandbox and i wonder if the transition component shouldn't receive tw classes.

https://codesandbox.io/s/twind-apply-react-typescript-73pm9?file=/src/components/Alert.tsx:1157-1417:

<Transition
      show={show}
      enter={tw`transition ease-out duration-100 transform`}
      enterFrom={tw`opacity-0`}
      enterTo={tw`opacity-100`}
      leave={tw`transition ease-in duration-200 transform`}
      leaveFrom={tw`opacity-100`}
      leaveTo={tw`opacity-0`}
    >

There are some really cool hidden gems like

• elevation for cards: https://codesandbox.io/s/twind-apply-react-typescript-73pm9?file=/src/components/Card.tsx:568-672

• the baseClasses and className pattern:

   export const Component = ({ children, className = "" }) => {
     const baseClasses = apply`bg-gray-900 text-white flex flex-wrap items-center justify-center py-2 px-2`;
  
     return (
       <div className={tw`${baseClasses} ${className}`}>{children}</div>
     );
   };

• the lazy directives pattern: https://codesandbox.io/s/twind-apply-react-typescript-73pm9?file=/src/App.tsx:627-818

  If this is something that is often used maybe could add an helper for that:

  import { lazy } from 'twind'
  
  const directives: InlineDirectiveMap<string> = {
    section: lazy`children:(m(1 md:2)) mb-4 p-2`,
    h3: lazy`font(semibold) text(gray-500 uppercase base) tracking-wide`
  };
  
  <section className={tw(directives.section)}>
    ....
  </section>

  lazy is just the first name that came to my mind. There may be better fits... deferred, define,...

[just214]

Yup, I agree about using tw for the transition. I have made this update.

Thanks for the feedback on the other things. Sorry I haven't had more time to convert this stuff into documentation. I'm going to have more time in the coming weeks and plan on helping with the docs.

The lazy helper idea is interesting. I don't know all of the inner workings of the inline directives,, but here are a few initial thoughts that come to mind:

• Could an inline function still be used to get the other context items, or how would they need to import these things explicitly? Or does it even make sense? section: ({theme}) => lazy`children:(m(1 md:2)) mb-4 p-2`, or maybe section: ({lazy, theme}) => lazy`children:(m(1 md:2)) mb-4 p-2`,
• If this is added to the lib, I think it would also be nice to also expose some version of InlineDirectiveMap type.
• One possible downside of this approach seems to be the lack of apparent way to pass props to make the lazy styles dynamic. I am guessing that might make non-cacheable styles and maybe defeats the purpose, but not quite sure?
• No need for a response on this one, but I do wonder: If you are able to cache the results of lazy without using an inline function, can this not also be done with the tw function?
• I feel like deferred is maybe a more "correct" name, but I like lazy. Ironically, because I am lazy and it's easier to type. I'd be curious to hear feedback from others if decided to move forward with this.

[sastan]

Yup, I agree about using tw for the transition. I have made this update.

👍

Thanks for the feedback on the other things. Sorry I haven't had more time to convert this stuff into documentation. I'm going to have more time in the coming weeks and plan on helping with the docs.

No worries... there are much more important things in life than this.

The lazy helper idea is interesting. I don't know all of the inner workings of the inline directives,, but here are a few initial thoughts that come to mind:

• Could an inline function still be used to get the other context items, or how would they need to import these things explicitly? Or does it even make sense? section: ({theme}) => lazy`children:(m(1 md:2)) mb-4 p-2`, or maybe `` section: ({lazy, theme}) => lazychildren:(m(1 md:2)) mb-4 p-2,

I see that this is one of the most confusing things in Twind. Let me try to explain the inner workings.

tw accepts strings, arrays and objects which is quite known from other libs. Additionally tw accepts functions aka inline directives. When generating the CSS and class names Twind call these inline directives with a context object which allows to access instance specific values like the theme. A inline directives can return an CSS object, a string or another inline directive. If it returns another inline directive that is called until a non function result is returned.

As a side note: a plugin is basically a named inline directive.

All other functions likes css, apply and theme, are optimized factories for inline directives. For example theme (sample implementation):

export const theme = (key) => ({ theme }) => theme(key)

theme('colors.white')
// => ({ theme }) => theme('colors.white')

This way we can defer the execution of our intent until we need it, eg until we are passing it the tw. This allows to compose these helper without actually executing anything.

const style = css`
  color: rebeccapurple;
  background-color: ${theme('colors.gray.500')};
  &:hover {
    ${apply`text-purple-700`}
  }
`

// Nothing executed yet; we only defined what should be executed

tw(style)
// => now all these directives get called

To come back to your question: I see these helpers are ways to avoid writing ({ theme, ...}) => ... all over the place. When reading these arrow functions it is not always obvious what is happing. lazy would eliminate the arrow functions for these calls:

import { lazy } from 'twind'

const section = lazy`children:(m(1 md:2)) mb-4 p-2`

// Instead of 
const section =({ tw }) => tw`children:(m(1 md:2)) mb-4 p-2`

As a nice little side effect we can optimize these helper. Here is an basic implementation:

const lazy = (...tokens) => ({ tw }) => tw(...tokens)

A real implementation may look like this:

import { directive } from 'twind'

const lazy$ = (tokens, { tw }) => tw(..tokens)

const lazy = (...tokens) => directive(lazy$, tokens)

The indirection allows caching based on the passed in tokens, eg the same function is returned for equal tokens (that allows tw to cache the result based on function identity):

lazy('text-center') === lazy('text-center')
lazy('text-center') !== lazy('text-left')

To be honest I would like to remove the inline directive concept or hide it in very very advanced section as it causes more confusion as it helps. Instead we should focus on promoting the use of the helpers.

• If this is added to the lib, I think it would also be nice to also expose some version of InlineDirectiveMap type.

That could be something like:

import type { Directive } from 'twind'

export type InlineDirectiveMap = Record<string, Directive>

• One possible downside of this approach seems to be the lack of apparent way to pass props to make the lazy styles dynamic. I am guessing that might make non-cacheable styles and maybe defeats the purpose, but not quite sure?

Something like this should be true:

const props = { align: 'center' }
lazy`text-${props.align}` === lazy`text-${'center'}`

• No need for a response on this one, but I do wonder: If you are able to cache the results of lazy without using an inline function, can this not also be done with the tw function?

lazy would allow to cache the returned inline directive which then helps tw to cache the result.

tw generates class names and as a side-effect injects the style into the page. The idea behind all the helpers is defining what should be done but do it only when passed to tw, eg later or never.

• I feel like deferred is maybe a more "correct" name, but I like lazy. Ironically, because I am lazy and it's easier to type. I'd be curious to hear feedback from others if decided to move forward with this.

Me too.

[just214]

This is an excellent explanation, thank you. This definitely helps to clarify the concepts as well as your thoughts behind them.

Just as a summary (please correct me if I my understanding is wrong on any of these):

lazy- Used to delay execution of styles. (advanced feature useful for performance optimizations)

apply- Used to compose styles into a single class that can be overwritten later in a tw call via a merger of styles. (advanced feature useful for component authors)

tw- This function takes care of composing any lazy and apply calls, etc. and injects the derived styles into the document.

Note: lazy and apply are not applied to the document until they are passed to a tw call.

[sastan]

That is a great summary! Have to put that into the docs.

theme – Use the theme value at this place (most useful within css)

And there are the ones from twind/css:

css – Create a single class using CSS declarations (advanced feature useful for the once-off styles)
animation – Create a animation directives
keyframe – Create a animation directives
screen – ...

[sastan]

@gojutin Do you have a twitter handle?

[just214]

Thanks! Ya, I think some version of this would be nice in the quick reference.

And no, I don't have a twitter account.