Skip to content

Commit 1e7f689

Browse files
micaiah-effiongmicaiah-effiong
authored
📝 updated documentation
Added syntax highlighting for code samples Increase readability by highlighing setions and titles
1 parent 138f811 commit 1e7f689

File tree

1 file changed

+133
-105
lines changed

1 file changed

+133
-105
lines changed

‎README.md

Lines changed: 133 additions & 105 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,29 @@
1-
<p style="font-size:2em"> Tailwind-children
1+
# Tailwind-children
2+
3+
Repeat elements without repeating styles
4+
`*.child`, `.sibling`, and `.descendant*` variants for [TailwindCSS v3+](https://tailwindcss.com)
25

3-
<div style='font-size:12px'> Repeat elements without repeating styles<br> *.child, .sibling, and .descendant* variants for [TailwindCSS v3+](https://tailwindcss.com). </div>
46
------
7+
58
# Installation
69

710
1. Install package:
8-
npm install tailwind-children --save
11+
```sh
12+
npm install tailwind-children --save
13+
```
914

1015
2. Add to tailwind.config.js
11-
12-
plugins: [
13-
require('tailwindcss-children'),
14-
]
16+
```js
17+
plugins: [
18+
require('tailwindcss-children'),
19+
]
20+
```
1521
3. Build tailwind:
16-
npx tailwindcss -i ./src/input.css -o ./dist/output.css
22+
```
23+
npx tailwindcss -i ./src/input.css -o ./dist/output.css
24+
```
1725

18-
# Usage: <div style='font-size:0.5em'>Pre-alpha. This <i>will</i> change!</div>
26+
## Usage: <br> Pre-alpha. This *will* change!
1927

2028
### child variant
2129
Set the styles in the parent and it will apply for all children with matching `child` class.
@@ -27,61 +35,66 @@ events set *before* the element will be applied to children.
2735
*Deprecated*:
2836
Use `child-*` modifiers like `child-hover` to apply state and psuedo-classes to children elements:
2937

30-
<!-- apply to all children with matching .child class -->
31-
<div class="overflow-hidden
32-
child:ring-white child-hover:shadow">
33-
<p class="child">I have a white ring...</p>
34-
<p class="child">And a shadow on hover!</p>
35-
</div>
36-
37-
<!-- apply to <p> elements, with shadow on hover -->
38-
<div class="overflow-hidden
39-
child-p:ring-white hover:child-p:shadow">
40-
<p>I have a white ring...</p>
41-
<p>And a shadow on hover!</p>
42-
</div>
38+
```html
39+
<!-- apply to all children with matching .child class -->
40+
<div class="overflow-hidden
41+
child:ring-white child-hover:shadow">
42+
<p class="child">I have a white ring...</p>
43+
<p class="child">And a shadow on hover!</p>
44+
</div>
4345

44-
### descendant variant
46+
<!-- apply to <p> elements, with shadow on hover -->
47+
<div class="overflow-hidden
48+
child-p:ring-white hover:child-p:shadow">
49+
<p>I have a white ring...</p>
50+
<p>And a shadow on hover!</p>
51+
</div>
52+
```
53+
54+
## Descendant variant
4555
Same usage, but includes non-direct descendants. Can use `descendant` or `heir` aliases
4656

47-
<div class="overflow-hidden
48-
heir:ring-white heir-hover:shadow">
49-
<div>
50-
<p class="heir">I have a white ring...</p>
51-
</div>
52-
<div>
53-
<p class="heir">And a shadow on hover!</p>
54-
</div>
57+
```html
58+
<div class="overflow-hidden
59+
heir:ring-white heir-hover:shadow">
60+
<div>
61+
<p class="heir">I have a white ring...</p>
5562
</div>
56-
57-
<div class="overflow-hidden
58-
descendant-p:ring-white hover:descendant-p:shadow">
59-
<div>
60-
<p>I have a white ring...</p>
61-
</div>
62-
<div>
63-
<p>And a shadow on hover!</p>
64-
</div>
63+
<div>
64+
<p class="heir">And a shadow on hover!</p>
6565
</div>
66+
</div>
6667

67-
68-
### sibling variant
69-
Same basic usage, but is applied to first of the repeating elements.
70-
Styles must be applied twice - once for itself and once for siblings with `sibling:` variant. (This has *some* duplication, but has an advantage that the styles are applied directly to the affected element and not to the parent.)
71-
68+
<div class="overflow-hidden
69+
descendant-p:ring-white hover:descendant-p:shadow">
7270
<div>
73-
<p class="
74-
ring-white hover:shadow
75-
sibling:ring-white sibling-hover:shadow">I have a white ring...</p>
76-
<p class="sibling">And a shadow on hover!</p>
71+
<p>I have a white ring...</p>
7772
</div>
78-
79-
<div>
80-
<p class="
81-
ring-white hover:shadow
82-
sibling-p:ring-white hover:sibling-p:shadow">I have a white ring...</p>
73+
<div>
8374
<p>And a shadow on hover!</p>
8475
</div>
76+
</div>
77+
```
78+
79+
## Sibling variant
80+
Same basic usage, but is applied to first of the repeating elements.
81+
Styles must be applied twice - once for itself and once for siblings with `sibling:` variant. (This has *some* duplication, but has an advantage that the styles are applied directly to the affected element and not to the parent)
82+
83+
```html
84+
<div>
85+
<p class="
86+
ring-white hover:shadow
87+
sibling:ring-white sibling-hover:shadow">I have a white ring...</p>
88+
<p class="sibling">And a shadow on hover!</p>
89+
</div>
90+
91+
<div>
92+
<p class="
93+
ring-white hover:shadow
94+
sibling-p:ring-white hover:sibling-p:shadow">I have a white ring...</p>
95+
<p>And a shadow on hover!</p>
96+
</div>
97+
```
8598

8699
# Rationale
87100

@@ -97,41 +110,46 @@ And its an issue which is surprising, as Tailwind's class based nature should ma
97110

98111
This, then, is an attempt to solve the issue of reusing styles through a plugin, and maybe @adam will see this and make it official :)
99112

100-
### The Issue
113+
## The Issue
101114

102115
To copy the example loosely from https://tailwindcss.com/docs/reusing-styles.
103-
Let's say you want to experiment with adding a shadow to all your `<img>s`.
116+
Let's say you want to experiment with adding a shadow to all your `<img>`s.
104117
Manually copying it in each one is slowly and buggy. What to do?
105118

106-
<div class="mt-3 flex -space-x-2 overflow-hidden">
107-
<img class="inline-block h-12 w-12 rounded-full ring-2 ring-white hover:shadow" src="/img0.jpg" alt=""/>
108-
<img class="inline-block h-12 w-12 rounded-full ring-2 ring-white hover:shadow" src="/img1.jpg" alt=""/>
109-
<img class="inline-block h-12 w-12 rounded-full ring-2 ring-white hover:shadow" src="/img2.jpg" alt=""/>
110-
<img class="inline-block h-12 w-12 rounded-full ring-2 ring-white hover:shadow" src="/img3.jpg" alt=""/>
111-
<img class="inline-block h-12 w-12 rounded-full ring-2 ring-white hover:shadow" src="/img4.jpg" alt=""/>
112-
</div>
119+
```html
120+
<div class="mt-3 flex -space-x-2 overflow-hidden">
121+
<img class="inline-block h-12 w-12 rounded-full ring-2 ring-white hover:shadow" src="/img0.jpg" alt=""/>
122+
<img class="inline-block h-12 w-12 rounded-full ring-2 ring-white hover:shadow" src="/img1.jpg" alt=""/>
123+
<img class="inline-block h-12 w-12 rounded-full ring-2 ring-white hover:shadow" src="/img2.jpg" alt=""/>
124+
<img class="inline-block h-12 w-12 rounded-full ring-2 ring-white hover:shadow" src="/img3.jpg" alt=""/>
125+
<img class="inline-block h-12 w-12 rounded-full ring-2 ring-white hover:shadow" src="/img4.jpg" alt=""/>
126+
</div>
127+
```
113128

114-
### A Proper Solution
129+
## A Proper Solution
115130

116131
Use `heir`, `child`, or `sibling` variants to target the respective elements (see usage above).
117132

118-
<div class="mt-3 flex -space-x-2 overflow-hidden
119-
child:inline-block child:h-12 child:w-12 child:rounded-full child:ring-2 child:ring-white child-hover:shadow">
120-
<img class="child" src="/img0.jpg" alt=""/>
121-
<img class="child" src="/img1.jpg" alt=""/>
122-
<img class="child" src="/img2.jpg" alt=""/>
123-
<img class="child" src="/img3.jpg" alt=""/>
124-
<img class="child" src="/img4.jpg" alt=""/>
125-
</div>
133+
```html
134+
<div class="mt-3 flex -space-x-2 overflow-hidden
135+
child:inline-block child:h-12 child:w-12 child:rounded-full child:ring-2 child:ring-white child-hover:shadow">
136+
<img class="child" src="/img0.jpg" alt=""/>
137+
<img class="child" src="/img1.jpg" alt=""/>
138+
<img class="child" src="/img2.jpg" alt=""/>
139+
<img class="child" src="/img3.jpg" alt=""/>
140+
<img class="child" src="/img4.jpg" alt=""/>
141+
</div>
142+
```
126143

127144
Isn't that nice?
128145

129-
### Perhaps, a better solution for sibling (not implemented)
146+
### A better solution for sibling (not implemented)
130147

131148
Add class `.siblings` to the first element, and that will set up a rule `.siblings ~ *` to apply the same rules to all of the siblings.
132149

133-
This will make it simple to experiment, easy to understand, is clean and is DRY. FTW!
134-
```
150+
This will make it simple to experiment, easy to understand, is clean and is **DRY**. **FTW**!
151+
152+
```html
135153
<div class="mt-3 flex -space-x-2 overflow-hidden">
136154
<img class="siblings inline-block h-12 w-12 rounded-full ring-2 ring-white hover:shadow" src="/img0.jpg" alt=""/>
137155
<img src="/img1.jpg" alt=""/>
@@ -144,30 +162,34 @@ This will make it simple to experiment, easy to understand, is clean and is DRY.
144162
Even better, we can have `siblings-of-type` to have it only apply said classes to peer elements with same tag.
145163
Admittedly, I do not know of any similar existing TW rule, but maybe it is just a matter of no need.
146164

147-
### Perhaps, a better solution for children (non-standard, not implemented)
165+
### A better solution for children (non-standard, not implemented)
148166

149167
Tailwind doesn't use other custom attributes, but I don't see why they shouldn't. CSS can handle any selectors, and we can prefix with tw- if we worry about conflict.
150168

151169
We can therefore create a children attribute with what ought to be applied to the children, and that would readable and DRY.
152170

153-
<div class="mt-3 flex -space-x-2 overflow-hidden"
154-
children="siblings inline-block h-12 w-12 rounded-full ring-2 ring-white hover:shadow"
155-
>
156-
<img src="/img0.jpg" alt=""/>
157-
<img src="/img1.jpg" alt=""/>
158-
<img src="/img2.jpg" alt=""/>
159-
<img src="/img3.jpg" alt=""/>
160-
<img src="/img4.jpg" alt=""/>
161-
</div>
171+
```html
172+
<div class="mt-3 flex -space-x-2 overflow-hidden"
173+
children="siblings inline-block h-12 w-12 rounded-full ring-2 ring-white hover:shadow"
174+
>
175+
<img src="/img0.jpg" alt=""/>
176+
<img src="/img1.jpg" alt=""/>
177+
<img src="/img2.jpg" alt=""/>
178+
<img src="/img3.jpg" alt=""/>
179+
<img src="/img4.jpg" alt=""/>
180+
</div>
181+
```
162182

163183
This would make a rather awkward css rule, but not one that affects the dev or the user:
164184
`[children="siblings inline-block h-12 w-12 rounded-full ring-2 ring-white hover:shadow"] > * { ... } `
165185

166186
To be sure, I think that Tailwind should offer this for all psuedo-classes:
167187

168-
<div class="block"
169-
tw-after="content-['wow'] text-white">...
170-
</div>
188+
```html
189+
<div class="block"
190+
tw-after="content-['wow'] text-white">...
191+
</div>
192+
```
171193

172194
And it is my hope that this plugin might be a foray into such usage!
173195

@@ -177,16 +199,18 @@ And it is my hope that this plugin might be a foray into such usage!
177199
Like every good project, Tailwind has a consistent style, and we should be consistent with it.
178200
Here are examples where a TW class effects another element:
179201

180-
<body class="dark">
181-
<p class="dark:shadow">p has shadow when dark theme enabled</p>
182-
</body>
202+
```html
203+
<body class="dark">
204+
<p class="dark:shadow">p has shadow when dark theme enabled</p>
205+
</body>
183206

184-
<input class="peer">
185-
<p class="peer-hover:shadow">p has shadow when hovering on input</p>
207+
<input class="peer">
208+
<p class="peer-hover:shadow">p has shadow when hovering on input</p>
186209

187-
<div class="group">
188-
<p class="group-hover:shadow">p has shadow when hovering over div</p>
189-
</div>
210+
<div class="group">
211+
<p class="group-hover:shadow">p has shadow when hovering over div</p>
212+
</div>
213+
```
190214

191215
In each of these examples,
192216
- we have the class on both the "calling" and "receiving" elements,
@@ -199,42 +223,46 @@ Therefore, in the first version of tailwind-children, we used the form `child-ho
199223
To match [@tailwindcss/typography], you can now use the form hover:child:shadow or hover:child-div:shadow.
200224
In addittion, you can still use child-hover:shadow, but not when specifying a element type.
201225

202-
Let's see how that works out for us:
226+
### Let's see how that works out for us:
203227

204228
1. When declaring a state, we can use the form `hover:child:shadow` with the hover *before* the child.
205229
- *Deprecated:* One can also use the form `child-hover:shadow`.
206230
This form cannot be used with a element type (eg. `child-div-hover:shadow` won't work).
207231
2. The rules only apply to children that have the matching `child/sibling/etc` class.
208232
To demonstrate, if wanted only one of two children to match, here are several options.
209233

210-
a. Require elements to "opt-in" with a "child" class
211-
```
234+
a. Require elements to "opt-in" with a "child" class
235+
```html
212236
<div class="child:shadow">
213237
<p class="child">Shadow</p>
214238
<p>No Shadow</p>
215239
</div>
216240
```
241+
217242
b. Apply style to all children, and allow children to override rules as needed.
218-
```
243+
```html
219244
<div class="child:shadow">
220245
<p>Shadow</p>
221246
<p class="drop-shadow-none">No Shadow</p>
222247
</div>
223248
```
249+
224250
c. Offer a no-child class that tells it to not inherit
225-
```
251+
```html
226252
<div class="child:shadow">
227253
<p>Shadow</p>
228254
<p class="no-child">No Shadow</p>
229255
</div>
230256
```
257+
231258
d. Only apply inheritance to element whose type is passed in. (Either `child-span` or `child-['span']`)
232-
```
259+
```html
233260
<div class="child-span:shadow">
234261
<span>Shadow</span>
235262
<p>No Shadow</p>
236263
</div>
237264
```
265+
238266
[tailwind-child] uses method d, and [@tailwindcss/typography] supports methods b, c and d.
239267
We hope to support all 4, but c is not yet implemented.
240268
3. No using a class to copy other classes. Excludes the "better sibling solution" above.
@@ -246,6 +274,6 @@ I might eventually implement it, even though it is not a tailwind style rule at
246274

247275
Please open issues, file bug reports, give me your opinions on variant names, default styles and behaviors, and whatever else you can think of. There are a lot of good things input can add!
248276

249-
[tailwindcss-children]: https://github.com/benface/tailwindcss-children
250-
[@tailwindcss/typography]: https://tailwindcss.com/docs/typography-plugin
251-
[tailwind-child]: https://github.com/racha/tailwind-child
277+
[tailwindcss-children](https://github.com/benface/tailwindcss-children) <br/>
278+
[@tailwindcss/typography](https://tailwindcss.com/docs/typography-plugin) <br/>
279+
[tailwind-child](https://github.com/racha/tailwind-child)

0 commit comments

Comments
 (0)