A project that strives to develop high-quality, community contributed Solid Primitives.

  • Small
    aggregate tree-shaking benefits
  • Isomorphic
    client and server side functionality
  • Stable
    consistent and managed testing + maintenance

Primitives

NameStagePrimitivesSizeNPM

Inputs

active-element
v2.0.20
autofocus
v0.0.111
input-mask
v0.2.2
keyboard
v1.2.8
mouse
v2.0.20
pointer
v0.2.19
scroll
v2.0.23
selection
v0.0.8

Display & Media

audio
v1.3.18
bounds
v0.0.122
devices
v1.2.6
filesystem
v1.2.2
idle
v0.1.2
intersection-observer
v2.1.6
media
v2.2.9
page-visibility
v2.0.17
resize-observer
v2.0.26
styles
v0.0.114

Browser APIs

broadcast-channel
v0.0.105
clipboard
v1.5.10
event-listener
v2.3.3
event-props
v0.2.7
fullscreen
v1.2.6
geolocation
v1.4.14
mutation-observer
v1.1.17
permission
v1.2.6
storage
v4.2.1
timer
v1.3.10
upload
v0.0.117
workers
v0.3.0

Network

connectivity
v0.3.20
cookies
v0.0.1
fetch
v2.4.9
graphql
v2.1.0
stream
v0.6.14
websocket
v1.2.2

Control Flow

context
v0.2.3
jsx-tokenizer
v1.0.10
keyed
v1.2.3
list
v0.0.101
range
v0.1.18
refs
v1.0.8

Utilities

controlled-props
v0.0.15
cursor
v0.0.115
date
v2.0.24
event-bus
v1.0.11
event-dispatcher
v0.0.107
flux-store
v0.0.4
history
v0.1.5
i18n
v2.1.1
platform
v0.1.2
promise
v1.0.17
props
v3.1.11
scheduled
v1.4.4
script-loader
v2.2.0
share
v2.0.6

Reactivity

deep
v0.2.10
destructure
v0.1.17
immutable
v1.0.10
lifecycle
v0.0.102
map
v0.4.13
memo
v1.3.10
mutable
v1.0.2
resource
v0.3.1
rootless
v1.4.5
set
v0.5.0
signal-builders
v0.1.17
state-machine
v0.0.3
static-store
v0.0.8
trigger
v1.1.0

UI Patterns

marker
v0.1.0
masonry
v0.0.7
pagination
v0.3.0
virtual
v0.1.0

Animation

presence
v0.0.6
raf
v2.2.0
spring
v0.0.1
transition-group
v1.0.5
tween
v1.3.0

#Contribution Process


StageDescription
XDeprecated or rejected
0Initial Submission
1Demonstrations and examples
2General use (experimental)
3Pre-shipping (final effort)
4Accepted/Shipped

Solid Primitives strives to provide idiomatic Solid principles but also allow room for innovation and experimentation. In a growing community many opinions and patterns merge together to produce a de facto standard. Managing opinions and expectations can be difficult. As a result, in November 2021 Solid Primitives implemented a ratification/approval tracking process roughly modelled on TC39 Proposal Stage Process. The following summarizes these stages briefly:

Any primitive Stage 01 should be used with caution and with the understanding that the design or implementation may change. Beyond Stage 2 we make an effort to mitigate changes. If a primitive reaches Stage 2 it's likely to remain an official package with additional approvement until fully accepted and shipped.

#Philosophy

The goal of Solid Primitives is to wrap client and server side functionality to provide a fully reactive API layer. Ultimately the more rooted our tertiary primitives are, the more they act as foundation within Solid's base ecosystem. With well built and re-used foundations, the smaller (aggregate tree-shaking benefits), more concise (readability) and stable (consistent and managed testing + maintenance) applications can be overall.

#Design Maxims

Other frameworks have large and extremely well established ecosystems. Notably React which has a vast array of component and hooks. The amount of choice within the ecosystem is great but often these tools are built as one-offs resulting in often un-tested logic or are designed with narrow needs. Over time the less concise these building blocks are the more they tend to repeat themselves. Our goal with Primitives is to bring the community together to contribute, evolve and utilize a powerful centralize primitive foundation.

All our primitives are meant to be consistent and sustain a level of quality. We guarantee that each is created with the utmost care. Our primitives are:

  1. Documented and follow a consistent style guide
  2. Be well tested
  3. Small, concise and practical as possible
  4. A single primitive for a single purpose
  5. No dependencies or as few as possible
  6. SSR safe entries (or short-circuits where needed) provided
  7. Wrap base level Browser APIs
  8. Should be progressively improved for future features
  9. Be focused on composition vs. isolation of logic
  10. Community voice and needs guide road map and planning
  11. Strong TypeScript support
  12. Support for both CJS and ESM
  13. Solid performance!

#Basic and Compound Primitives

Each primitive is designed with composition in mind. A major rule in designing our primitives is deciding that the interface of primitives should be composable or segmented. For this reason every API is intricately studied and considered to be composed (stacked with features) or decomposed into smaller units. Designing our primitives in this manner allows for better tree-shaking and extendable complexity only as needed. You should only ship what you have to by picking from existing primitives as your foundational building blocks.

Much of the design decisions in naming are best described in the 7 Lessons to Outlive React talk by swyx. We strive to follow a similar design pattern promoted by the React core team.

#make (non-reactive) vs create (reactive)

Solid uses the create prefix to define a primitive that provides reactive utility. Solid Primitives reinforces this pattern but in an effort to enhance composability we have also introduced the make prefix for identifying non-reactive foundation primitives. Having a non-reactive alternative means that the primitive does the bare essentials such as cleaning up events or interupting a process. ie. makeTimer will create and clean-up the scheduler, providing only a clear method. createTimer provides a properly reactive primitive that composes it.

#Managing Primitive Complexity

Solid Primitives is mostly about supplying 80-90% of the common-use cases for the end-user. We prefer to be less prescriptive than other hook libraries such as VueUse and supply granular solutions as opposed to monolithic primitives. The remaining 10-20% of complex use cases are likely not to be covered with this library. This is on purpose to limit the potential of bloat and extended complexity. This project strives to provide foundations and not cumulative solutions. We expect the broader ecosystem will fill the remaining need as further composition to this projects effort. This allows for just the right amount of prescription and opinion.