Twind

Module: twind/sheets

DocumentationGithubModule SizeTypescript

This module provides virtualSheet and domSheet which can be used with setup({ sheet }).

Virtual Sheet

The virtual sheet collects style rules into an array. This is most useful during testing and {@page Extract Styles aka SSR | server side rendering (SSR)}.

Additionally it provides an API to reset the current internal state of its tw function.

Using for Static Extraction a.k.a. Server Side Rendering (SSR)

💡 You can find detailed instructions and example in the {@page Extract Styles aka SSR | Server Side Rendering (SSR) guide}.

The following example assumes your app is using the tw named export from twind but the same logic can be applied to custom instances.

import { setup } from 'twind'
import { virtualSheet, getStyleTag } from 'twind/sheets'

const sheet = virtualSheet()

setup({ ...sharedOptions, sheet })

function ssr() {
  // 1. Reset the sheet for a new rendering
  sheet.reset()

  // 2. Render the app
  const body = renderTheApp()

  // 3. Create the style tag with all generated CSS rules
  const styleTag = getStyleTag(sheet)

  // 4. Generate the response html
  return `<!DOCTYPE html>
    <html lang="en">
      <head>${styleTag}</head>
      <body>${body}</body>
    </html>
  `
}

Using in tests

💡 The example below uses uvu. Please adjust the test code to your testing framework.

import { suite } from 'uvu'
import * as assert from 'uvu/assert'

import { create } from 'twind'
import { virtualSheet } from 'twind/sheets'

const test = suite('using virtual sheet')

// Setup code to be run once before all tests
test.before((context) => {
  context.sheet = virtualSheet()

  const instance = create({
    sheet: context.sheet,
    // Fail tests on unknown rules or theme values
    mode: 'strict',
    // Prevent preflight rules to be added into sheet
    preflight: false,
    // Do not prefix properties and values
    prefix: false,
  })

  context.tw = instance.tw
})

// Clear the state before each test
test.before.each(({ sheet }) => {
  sheet.reset()
})

test('render one rule', ({ tw, sheet }) => {
  assert.is(tw`text(center)`, 'text-center')
  assert.equal(sheet.target, '.text-center{text-align:center}')
})

DOM Sheet

This sheet uses DOM Text nodes to insert the CSS rules into the stylesheet. Using DOM manipulation makes this way slower than the default sheet but allows to see the generated CSS in to DOM. Most modern browser display CSS rules from the speedy default sheet using their CSS inspector.

💡 In production it is advised to use speedy default sheet.

If the domSheet is passed no target it looks for an style element with the id __twind. If no such element is found it will create one and append it to the document.head.

import { setup } from 'twind'
import { domSheet } from 'twind/sheets'

setup({ ...sharedOptions, sheet: domSheet() })

Custom Sheet Implementation

In case the builtin sheet implementations do not solve your use case, you can create your own:

import { setup } from 'twind'

const customSheet = (target = []) => ({
  target,
  insert: (rule, index) => {
    // rule: the CSS rule to insert
    // index: the rule's position
    target.splice(index, 0, rule)
  },
})

setup({ ...sharedOptions, sheet: customSheet() })

Table of contents

Interfaces

Type aliases

StyleTagSheet

Ƭ StyleTagSheet: HasTarget | readonly string[]

Defined in: src/sheets/index.ts:98

Functions

domSheet

â–¸ ConstdomSheet(options?: SheetConfig<HTMLStyleElement>): Sheet<HTMLStyleElement>

Creates an sheet which inserts style rules through the Document Object Model.

Parameters:

NameTypeDefault value
optionsSheetConfig<HTMLStyleElement>{}

Returns: Sheet<HTMLStyleElement>

Defined in: src/sheets/index.ts:14

getStyleTag

â–¸ ConstgetStyleTag(sheet: StyleTagSheet, attributes?: Record<string, string>): string

Transforms css rules into a <style> tag string.

Parameters:

NameType
sheetStyleTagSheet
attributes?Record<string, string>

Returns: string

Defined in: src/sheets/index.ts:111

getStyleTagProperties

â–¸ ConstgetStyleTagProperties(sheet: StyleTagSheet): StyleTagProperties

Transforms css rules into <style> tag properties.

Parameters:

NameType
sheetStyleTagSheet

Returns: StyleTagProperties

Defined in: src/sheets/index.ts:103

virtualSheet

â–¸ ConstvirtualSheet(): VirtualSheet

Creates an sheet which collects style rules into an array.

Returns: VirtualSheet

Defined in: src/sheets/index.ts:72